API REFERENCE
Authentication Docs
Getting Started
SAP Concur's new Oauth2 framework is a very simple way to implement a Unified Token Authentication mechanism within your application. Here is a four step guide to helping you get up to speed and making calls to SAP Concur's API.
Note: The Pre-2017 Authorization (Deprecated) documentation can be found here
- Obtain Your Application clientID and clientSecret
- Obtaining an Access Token
- Calling an API with the Access Token
- Access Token Expiry and Obtaining a Fresh One
Obtain clientID and clientSecret
Before you can obtain an accessToken, you need to register an application with SAP Concur. You can do this by contacting your Partner Enablement Manager or Partner Account Manager. Once you have registered an application, you will receive a clientId, clientSecret and geolocation. The clientId is a unique UUID4 identifier for your application, and the clientSecret is your application's password. You will be using this credential to obtain tokens either for the application itself, or on behalf of a user. The geolocation is your default base URI for initiating all new connections.
Obtaining an Access Token
In order for an application to call a SAP Concur API, you need to obtain an accessToken on behalf of either a User, Company or Application. There are multiple ways of obtaining an accessToken through the various grants (Password, Authorization, Client Credentials, One-time Password) .
This section provides a quick start guide for generating an access token. If you are developing an application to be certified for the App Center or as a TripLink supplier, please refer to the certification documentation for the grant types your application must support.
For simplicity, we will use the Password grant flow as an example. The Password grant flow is used when you need to authenticate a user, using its username and password. This is typically reserved from SAP Concur applications (i.e. where the user's credentials will be captured and stored) but is used here for demonstration purposes.
When making the call, you will use your app's geolocation as the base URI followed by the endpoint. For example, if your geolocation is https://us.api.concursolutions.com, you will call https://us.api.concursolutions.com/oauth2/v0/token.
The first time you request for an accessToken a refreshToken is also returned. There are certain conditions where a refreshToken is not returned. This is used to get a new accessToken when one has expired. (see below for more info)
Example shell script using cURL to obtain an accessToken:
oauth2_base=https://us.api.concursolutions.com/oauth2
username=<concur_username> eg. john.doe@gmail.com
password=<password> eg. password1
client_id=<clientId> eg. e01f725d-b4ce-4ce3-a664-b670cb5876cb0
client_secret=<clientSecret> eg. 35c3bd92-fcb8-405e-a886-47ff3fba5664
curl -X POST -H 'concur-correlationid: nameofapp' "$oauth2_base/v0/token" --data "username=$username&password=$password&grant_type=password&client_secret=$client_secret&client_id=$client_id"
Full docs: https://developer.concur.com/slate-ui/build/api-reference.html#password-grant
Store the token and geolocation.
Calling an API with Access Token
Once you have the accessToken, you need to supply this in an Authorization header in the form of Authorization: Bearer <accessToken> when making a HTTPS call. The accessToken is a large string that looks something like this:
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTU2MTQzNDYifQ.eyJhdWQiOiIqIiwic3ViIjoiaHR0cDovL21zcGNzcHJzcnFhLmNvbmN1ci5jb25jdXJ0ZWNoLm9yZzozMDAzL3Byb2ZpbGUtc2VydmljZS92MS91c2Vycy83NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJpc3MiOiJodHRwczovL2NvbmN1ci5jb20iLCJleHAiOjE0NzM4OTUxMjksImxlZ2FjeV9hcHBsaWNhdGlvbl9pZCI6MTUwMDA2MzY1OSwidXNlclVSSSI6Imh0dHA6Ly9tc3Bjc3Byc3JxYS5jb25jdXIuY29uY3VydGVjaC5vcmc6MzAwMy9wcm9maWxlLXNlcnZpY2UvdjEvdXNlcnMvNzYwMDlBRDMtRjc3Qi00RDk4LUEyMUEtNTUzQzlDOTE3OUYwIiwidXNlcnV1aWQiOiI3NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJuYmYiOjE0NzM4OTE1MjksImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vYXBwIjoiaHR0cHM6Ly9hcGkuY29uY3Vyc29sdXRpb25zLmNvbS9hcHAtbWdtdC92MC9hcHBzL2UwMTBlMjVkLWI0Y2UtNGNlMy1hN2U0LWI2NzBjYjFhZGNiMCIsImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vc2NvcGVzIjpbIkNDQVJEIiwiQ09NUEQiLCJVU0VSIiwidXNlcl9yZWFkIiwiRU1FUkciLCJKT0JMT0ciLCJFUkVDUFQiLCJJVElORVIiLCJGSVNWQyIsIkxJU1QiLCJQQVNTViIsIkNPTkZJRyIsIkZPUCIsIkdIT1NUIiwiQ09OUkVRIiwiVFJJUElUIiwiQ09NUEFOWSIsInByb2ZpbGUiLCJFVlMiLCJlbWFpbCIsIlRSVlBUUyIsIkFUVEVORCIsIklOVlBPIiwiTk9USUYiLCJUUlZSRVEiLCJTVVBTVkMiLCJFWFBSUFQiLCJhZGRyZXNzIiwiRVhUUkNUIiwiUEFZQkFUIiwid3Jvbmdfc2NvcGUiLCJJTlZQTVQiLCJJTUFHRSIsIlRBWElOViIsIlJDVElNRyIsIlVOVVRYIiwiVFdTIiwiVE1DU1AiLCJCQU5LIiwiSU5WVkVOIiwib3BlbmlkIiwiTVRORyIsIklOU0dIVCIsIlRSVlBSRiIsIklOVlRWIiwiTUVESUMiLCJUU0FJIl0sImlhdCI6MTQ3Mzg5MTUyOX0.QHY4Mc5A3J981-HDv7KUdgS4tUI-qnmQAxwe9J6DHxuMmYSoGEYZ0dsnLnqc2lO2iVJK6Pg3EBZTArq8_vzV2FK7tA4-IT1eCEHo1e-RWZyWLnR7P56SvZozXpY73daovSH7572HrUm21FXcyLmdaLZyo2LfFcChaghbSCjm1Jg1duH-pLPUW4d89-_pdakmyxfV3GCm2N_XQXoRhNYAAiZcG8UfxEn3TpMHJ96F2n6keJanT_Sn2Sek_sH2EmeeCpg5-jDe0fvLvr1-gY5t0ifq8QBKWHSUUIrGbQvseD6CGzfyiFUqVypN2lukfWACR-26otN50c0OzY6kgY06RA
When you receive the accessToken, store it with the token's geolocation. That geolocation will be the base URI for all subsequent calls.
Armed with the accessToken you can start making calls to SAP Concur's API. Here's an example to retrieve profile information for a User in the Production environment using cURL (utilize the appropriate base URI geolocation for the token). Base URIs Reference:
curl -k -v -H "Accept: application/json" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTU2MTQzNDYifQ.eyJhdWQiOiIqIiwic3ViIjoiaHR0cDovL21zcGNzcHJzcnFhLmNvbmN1ci5jb25jdXJ0ZWNoLm9yZzozMDAzL3Byb2ZpbGUtc2VydmljZS92MS91c2Vycy83NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJpc3MiOiJodHRwczovL2NvbmN1ci5jb20iLCJleHAiOjE0NzM4OTUxMjksImxlZ2FjeV9hcHBsaWNhdGlvbl9pZCI6MTUwMDA2MzY1OSwidXNlclVSSSI6Imh0dHA6Ly9tc3Bjc3Byc3JxYS5jb25jdXIuY29uY3VydGVjaC5vcmc6MzAwMy9wcm9maWxlLXNlcnZpY2UvdjEvdXNlcnMvNzYwMDlBRDMtRjc3Qi00RDk4LUEyMUEtNTUzQzlDOTE3OUYwIiwidXNlcnV1aWQiOiI3NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJuYmYiOjE0NzM4OTE1MjksImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vYXBwIjoiaHR0cHM6Ly9hcGkuY29uY3Vyc29sdXRpb25zLmNvbS9hcHAtbWdtdC92MC9hcHBzL2UwMTBlMjVkLWI0Y2UtNGNlMy1hN2U0LWI2NzBjYjFhZGNiMCIsImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vc2NvcGVzIjpbIkNDQVJEIiwiQ09NUEQiLCJVU0VSIiwidXNlcl9yZWFkIiwiRU1FUkciLCJKT0JMT0ciLCJFUkVDUFQiLCJJVElORVIiLCJGSVNWQyIsIkxJU1QiLCJQQVNTViIsIkNPTkZJRyIsIkZPUCIsIkdIT1NUIiwiQ09OUkVRIiwiVFJJUElUIiwiQ09NUEFOWSIsInByb2ZpbGUiLCJFVlMiLCJlbWFpbCIsIlRSVlBUUyIsIkFUVEVORCIsIklOVlBPIiwiTk9USUYiLCJUUlZSRVEiLCJTVVBTVkMiLCJFWFBSUFQiLCJhZGRyZXNzIiwiRVhUUkNUIiwiUEFZQkFUIiwid3Jvbmdfc2NvcGUiLCJJTlZQTVQiLCJJTUFHRSIsIlRBWElOViIsIlJDVElNRyIsIlVOVVRYIiwiVFdTIiwiVE1DU1AiLCJCQU5LIiwiSU5WVkVOIiwib3BlbmlkIiwiTVRORyIsIklOU0dIVCIsIlRSVlBSRiIsIklOVlRWIiwiTUVESUMiLCJUU0FJIl0sImlhdCI6MTQ3Mzg5MTUyOX0.QHY4Mc5A3J981-HDv7KUdgS4tUI-qnmQAxwe9J6DHxuMmYSoGEYZ0dsnLnqc2lO2iVJK6Pg3EBZTArq8_vzV2FK7tA4-IT1eCEHo1e-RWZyWLnR7P56SvZozXpY73daovSH7572HrUm21FXcyLmdaLZyo2LfFcChaghbSCjm1Jg1duH-pLPUW4d89-_pdakmyxfV3GCm2N_XQXoRhNYAAiZcG8UfxEn3TpMHJ96F2n6keJanT_Sn2Sek_sH2EmeeCpg5-jDe0fvLvr1-gY5t0ifq8QBKWHSUUIrGbQvseD6CGzfyiFUqVypN2lukfWACR-26otN50c0OzY6kgY06RA" \
https://us.api.concursolutions.com/profile/v1/me
and the response will look like:
{
"addresses": [
{
"type": "Home",
"streetAddress": "",
"locality": "",
"region": "",
"postalCode": "",
"country": "US"
},
{
"type": "Work",
"streetAddress": "",
"locality": "",
"region": "",
"postalCode": "",
"country": "US"
}
],
"travelIds": {
"userId": 85663431,
"companyId": "63E447F6-A6A7-4B70-A951-10F45d693B43",
"companyInternalId": 222458,
"setId": 91157361,
"ruleClassId": 394103,
"travelConfigId": 0
},
"meta": {
"created": "2016-06-08T00:00:00.000",
"lastModified": "2016-08-22T14:32:00.000",
"resourceType": "EnterpriseUser"
},
"displayName": "Brown",
"name": {
"formatted": "Brown, Terry ",
"familyName": "Brown",
"givenName": "Terry",
"middleName": "",
"honorificPrefix": "",
"honorificSuffix": ""
},
"phoneNumbers": [
{
"type": "Home",
"value": "tel:+1-4251231244",
"primary": false,
"notifications": false,
"countryCode": "US",
"countryISDCode": "1"
},
{
"type": "Work",
"value": "tel:+1-4251231234;ext=",
"primary": false,
"notifications": false,
"countryCode": "US",
"countryISDCode": "1"
}
],
"com:concur:Employee:1.0": {
"employeeId": "brown@brown-sandbox.com",
"jobTitle": "",
"managerId": null,
"orgUnitId": null
},
"dateOfBirth": null,
"schemas": [
"com:concur:User:1.0",
"com:concur:Employee:1.0"
],
"active": true,
"id": "e01f725d-b4ce-4ce3-a664-b670cb5876cb0",
"com:concur:TravelPreferences:1.0": {
"air": {
"seat": {
"interrowPosition": null,
"sectionPosition": null
},
"meal": "DontCare",
"homeAirport": null
},
"rail": {
"space": "DontCare",
"meal": "DontCare",
"bedCategory": "DontCare",
"fareSpaceComfort": "DontCare",
"deck": "DontCare",
"coach": "DontCare",
"bed": "DontCare",
"berth": "DontCare",
"noiseComfort": "DontCare",
"contingency": "DontCare",
"seat": "DontCare"
},
"car": {
"smoking": "DontCare",
"carType": "DontCare",
"transmission": "DontCare",
"gpsEnabled": false,
"skirack": false
},
"hotel": {
"earlyCheckin": false,
"remark": null,
"pool": false,
"roomService": false,
"foamPillows": false,
"accessForBlind": false,
"accessForWheelchair": false,
"gym": false,
"roomType": "DontCare",
"restaurant": false,
"rollawayBed": false,
"smoking": "DontCare",
"crib": false
}
},
"gender": null,
"emails": [
{
"value": "brown@brown-sandbox.com",
"type": "Business",
"notifications": true
}
],
"userType": "Enterprise"
}
Full docs: https://developer.concur.com/slate-ui/build/api-reference/user/
Access Token Expiry and Obtaining a Fresh One
Access Tokens have a default One hour lifetime. In order to obtain a fresh accessToken you need to call the auth endpoint using the Refresh Grant. This will return a brand new accessToken and a refreshToken. Refresh Tokens have a default 6 month lifetime. Clients will typically store the refreshToken together with the other user metadata like login information and unique identifiers.
Utilizing the geolocation for the token, here's an example of a cURL call to obtain a new accessToken
curl -X POST 'https://us.api.concursolutions.com/oauth2/v0/token' --data "client_id=$client_id&client_secret=$client_secret&grant_type=refresh_token&refresh_token=<old refresh token>"
Full docs: https://developer.concur.com/slate-ui/build/api-reference/authentication/apidoc.html#refresh_token
Now that you've made your first call, read up more about SAP Concur's wide ranging APIs and how they can enhance your application or solve your business needs.
ref: https://developer.concur.com/slate-ui/build/api-reference/index.html
Authentication
Special Note: (Please Read First)
If you are an existing partner with an existing app, please read both the Migration to Oauth2 Tokens and Getting Started documentation first. If you have any questions, please contact your Partner Enablement team representative before proceeding.
- Overview
- Tokens
- Types of grants
- Response Codes
- Troubleshooting
Note: The Pre-2017 Authorization (Deprecated) documentation be found here
Access Tokens
The Oauth2 service generates access tokens for authenticated users, applications or companies. The token returned in the Oauth2 response can be used to access protected resources on SAP Concur services.
The Oauth2 response can, depending on grant type contain these values:
| Name | Type | Format | Description |
|---|---|---|---|
expires_in |
string |
- | The lifetime in seconds of the access token |
scope |
string |
- | The scope of the access token as granted to the client application |
token_type |
string |
- | The type of token returned. Value will be Bearer |
access_token |
string |
- | Token used to access protected resources of SAP Concur services. |
refresh_token |
string |
- | Refresh token required to request a new access token for a given user. |
geolocation |
string |
- | The base URL for where the user profile lives. See base URI for usage. |
id_token |
string |
- | The OCID Token in the JSON Web Token (JWT) format that describes the user or company |
Token Response
HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close
{
"expires_in": "3600",
"scope": "app-scopes",
"token_type": "Bearer",
"access_token": "access_token",
"refresh_token": "refresh_token",
"id_token": "ocid_token",
"geolocation": "https://us.api.concursolutions.com"
}
Obtaining a token
You can obtain a token for three different types of principals in the SAP Concur universe.
- User
- Application
- Company
Token Lifetime
An accessToken has a one hour lifetime.
In order to obtain a token, the client application needs to call the Oauth2 endpoint using various grants depending on the authentication scenarios required. The full list of supported scenarios is provided below:
Refreshing a token
The refresh grant is used to refresh an access_token that has expired. This grant can be used anytime a refresh_token is returned in the response of another grant request. No user interaction is required.
Token Lifetime
A refresh token has a six month lifetime. If the refresh token expires, the client application must reinitiate the authorization process. When a refresh token is used to request a new access token, both a new access token as well as a new refresh token are returned in the response. This token can change even if most of the time, this value is the same. Client applications should treat all returned refresh tokens as new tokens and overwrite the stored tokens with the new token from the response.
It is recommended that the client application use the refresh grant to request a new access token as the initial step of accessing protected resources of SAP Concur services.
Refreshing the token
To request a new access token using a valid refresh token, use the Oauth2 /token endpoint. Use the application/x-www-form-urlencoded content type.
POST /oauth2/v0/token
Post Body
| Name | Type | Format | Description |
|---|---|---|---|
client_id |
string |
UUID |
Required The client applications client_id supplied by App Management |
client_secret |
string |
UUID |
Required The client applications client_secret supplied by App Management |
refresh_token |
string |
UUID |
Required An existing valid refresh token to be used to request a new access token |
scope |
string |
- | Optional The client applications list of scopes |
grant_type |
string |
- | Required The grant type instructs the Oauth2 service how to process the request. For refresh token, the value must be refresh_token |
Request
POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 437
POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=refresh_token
&refresh_token=valid-refresh_token
&scope=app-scope
Response
HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close
{
"expires_in": "3600",
"scope": "app-scopes",
"token_type": "Bearer",
"access_token": "access_token",
"refresh_token": "refresh_token",
"id_token": "ocid_token",
"geolocation": "https://us.api.concursolutions.com"
}
Revoking a token
All refresh_tokens associated to a user for an application can be revoked by calling the https://us.api.concursolutions.com/app-mgmt/v0/connections endpoint with a DELETE action. You have to provide the User's accessToken in the Authorization Header as Authorization: Bearer <access_token>.
DELETE https://us.api.concursolutions.com/app-mgmt/v0/connections
Request
DELETE https://us.api.concursolutions.com/app-mgmt/v0/connections
Authorization: Bearer {token}
Response
HTTP/1.1 200 OK
Managing tokens
Refresh Tokens are UUID4 identifiers that allow your application to obtain a fresh accessToken on behalf of a user to access SAP Concur APIs.
e013335d-b4ce-4c43-a7e4-b67abc1adcb0
It is highly recommended that you store Refresh Tokens together with your user's authorization metadata in your application every time you obtain a new refreshToken as they might change depending on different scenarios.
FOR APP CENTER AND SUPPLIER PARTNERS supporting all geolocations, storing the authorization metadata, including the geolocation are REQUIRED.
Base URIs
When making API calls, the appropriate base URI should be used. There are three different scenarios: 1. Obtaining a token for a user. 2. Refreshing a token. 3. Calling other APIs.
The base URI for obtaining a token will leverage your application's geolocation. The base URI for refreshing tokens and all other API calls will leverage the token's geolocation.
Base URIs for Obtaining a Token
When your application is created, you will be provided with a client ID, secret and geolocation. When obtaining a token, your application should use the base URI for the geolocation in which your application exists.
There are two endpoints for each geolocation - one is the default (used for server-side calls) and the other should be used for client-side calls.
The full list of available token geolocations is available on the Base URIs page.
When obtaining the token, the token's geolocation will be included in the response. The token's geolocation should be stored along with the token. The Developer's app will then be able to make subsequent calls using the token and the correct end points based on the token's GEO location.
Base URIs for All Other Calls
When refreshing a token or when calling any other APIs, the token's geolocation should be used as the base URI.
Note: Client-side calls should use the www- variant of the base URI.
For example: When obtaining a token, if the response was the below:
HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close
{
"expires_in": "3600",
"scope": "app-scopes",
"token_type": "Bearer",
"access_token": "access_token",
"refresh_token": "refresh_token",
"id_token": "ocid_token",
"geolocation": "https://us.api.concursolutions.com"
}
When then calling the receipts API to post a receipt, your request should be made to https://us.api.concursolutions.com (if server side) or https://www-us.api.concursolutions.com (for clients).
ID Token
Authentication service will return an OPENID compatible ID token with every token request. This id_token is primarily used to describe information about a user or a company. You can obtain the userId from this token.
Sample id_token:
{
"aud": "e010e25d-b4ce-4ce3-a7e4-b670cb1adcb0",
"concur.profile": "https://us.api.concursolutions.com/profile/v1/principals/76459ad3-f77b-4d98-a21a-55333c9179f0",
"concur.version": 2,
"concur.type": "user",
"sub": "76459ad3-f77b-4d98-a21a-55333c9179f0",
"iss": "https://us.api.concursolutions.com",
"exp": 1485485529,
"nbf": 1485481929,
"at_hash": "351515a6482f4ee1",
"iat": 1485481929
}
Verifying an id_token
The Authentication service exposes JWKs that can be used to validate the id_token in the form of a JWT. Validating a JWT is described in detail in RFC 7519 - sec 7.2
This is the link to the SAP Concur JSON Web Key for Oauth2. https://www-us.api.concursolutions.com/oauth2/v0/jwks
Authorization grant
The authorization grant is the regular 3-legged oauth2 grant and is defined in detail in RFC6749 sec-4.1. This grant requires the user to explicitly authenticate themselves and authorise the application initiating the grant.
The users must be able to authenticate themselves via an SAP Concur username & password. Users will be challenged to login by an Oauth2 HTML page.
Who should use it * 3rd party "partner" websites - or - * non-SAP Concur Applications - & - * Applications that need explicit user authentication & authorization - & - * Applications that can securely store a code, access_token & refresh_token
Grant details
Note that the grant type must be accessed using the
www-version of the API Gateway in order to avoid certificate issues with some browsers. (ex: https://www-us.api.concursolutions.com instead of https://us.api.concursolutions.com)
GET /oauth2/v0/authorize
| Name | Type | Format | Description |
|---|---|---|---|
client_id |
string |
UUID |
Applications client_id supplied by App Management |
redirect_uri |
string |
- | The redirect URI for your application to continue with the Oauth2 flow |
scope |
string |
- | List of scopes that application is asking for |
response_type |
string |
- | code |
state |
string |
- |
With this grant, the user has two authentication options: 1. Username and password 2. One-time link using a verified email address
With both options, once the user is successfully authenticated and the user authorizes your application, the user will be redirected to the redirect_URI specified in the initial /authorize call with a temporary token appended.
<redirect_uri>?geolocation=<token_geolocation>&code=<token>
If the user is not successfully authenticated or does not authorize the scopes for your application, an error code and description will be appended to the redirect URI. Please refer to the Response Codes section for more information.
Your application must then exchange the temporary token for a long-lived token using the below.
POST /oauth2/v0/token
| Name | Type | Format | Description |
|---|---|---|---|
client_id |
string |
UUID |
Applications client_id supplied by App Management |
client_secret |
string |
UUID |
Applications client_secret supplied by App Management |
redirect_uri |
string |
- | The redirect_uri that is registered for the application |
code |
string |
UUID |
The authorization code provided by Auth |
grant_type |
string |
- | authorization_code |
Password grant
The Password grant can be used when there is a trust relationship between the user and the application. There are two credential types allowed with Password Grant:
- "Password": with this credential type, the application either already has the user's credentials or can obtain the user's credentials by directly interacting with the user.
- "AuthToken": This credential type is used for connections from the App Center. For App Center partners and TripLink suppliers, please refer to the certification documentation for more information.
Post Body
| Name | Type | Format | Description |
|---|---|---|---|
client_id |
string |
UUID |
Applications client_id supplied by App Management |
client_secret |
string |
UUID |
Applications client_secret supplied by App Management |
grant_type |
string |
- | Specify which grant type you expect the oauth2 service to process. for password grant, the value is password |
username |
string |
- | specify the username or userId |
password |
string |
- | specify the user's password |
credtype |
string |
- | The credtype signifies to oauth2 which credential set is being submitted in the request. There are two supported values: authtoken and password. For connections from the App Center, use authtoken. if omitted, oauth2 will assume the type is password. |
Request
POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 175
POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=password
&username=username
&password=password
Response
HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close
{
"expires_in": "3600",
"scope": "app-scopes",
"token_type": "Bearer",
"access_token": "access_token",
"refresh_token": "refresh_token",
"id_token": "ocid_token",
"geolocation": "https://us.api.concursolutions.com"
}
example bad login
{
"error": "invalid_grant",
"error_description": "Incorrect Credentials. Please Retry",
"code": 5
}
Client Credentials grant
Use the application/x-www-form-urlencoded content type.
POST /oauth2/v0/token
Post Body
| Name | Type | Format | Description |
|---|---|---|---|
client_id |
string |
UUID |
Required Applications client_id supplied by App Management |
client_secret |
string |
UUID |
Required Applications client_secret supplied by App Management |
grant_type |
string |
- | Required Specify which grant type you expect the oauth2 service to process. For client_credentials grant, the value is client_credentials |
Request
POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 127
POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=client_credentials
Response
HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 1626
Connection: Close
{
"expires_in": "3600",
"scope": "app-scopes",
"token_type": "Bearer",
"access_token": "access_token",
"geolocation": "https://us.api.concursolutions.com"
}
One Time Password grant
The One-time Password grant type leverages email, phone (text messaging), instant messaging and similar systems to provide per user access tokens to client applications. This grant type requires the following steps:
- The calling application calls the OAuth2 service specifying the otp grant type along with required parameters.
- The OAuth2 service generates a one time token which it sends through the messaging mechanism chosen by the application.
- The user retrieves the token and presents it to the application. The means of having this presented to the application is the responsibility of the application.
- The application presents this one-time token to the OAuth2 service via the token endpoint.
Request a one-time token to be sent to the user
Use the application/x-www-form-urlencoded content type.
POST /oauth2/v0/otp
Post Body
| Name | Type | Format | Description |
|---|---|---|---|
client_id |
string |
UUID |
Required The client_id as defined in the SAP Concur application management system. |
client_secret |
string |
UUID |
Required The client_secret as set by the client owner in the SAP Concur application management system. |
channel_handle |
string |
- | Required The location (email address, phone number) where the one time token should be sent. Currently, only email address is valid. |
channel_type |
string |
- | Required The type of messaging system to use. Currently only email is valid |
name |
string |
- | Optional The name of the user that appears in the email. |
company |
string |
- | Optional The company or application name that appears in the email. |
link |
string |
- | Optional The callback URL that appears in the email for users to click to complete the auth flow. |
The calling application code can also append n-number of unique client defined parameters in the URI for the purpose of connecting the one time token to the application when received by the user. The names of these parameters cannot conflict with the API defined parameters.
The following are reserved words and cannot be used as client application defined parameters:
/otp: "client_id" "client_secret" "channel_type" "channel_handle"
/token: "client_id" "client_secret" "channel_type" "channel_handle" "scope" "grant_type" "otp"
If the calling application chooses to send custom parameters, all of these exact same parameters must be included in subsequent API calls to acquire the access token. In other words, the URI signature, modulo the one time token parameter itself and token service specific parameters, must match the originating URI signature.
Request
POST /oauth2/v0/otp HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Host: us.api.concursolutions.com
Connection: close
Content-Length: 437
POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&channel_handle=email adress
&channel_type=valid-email
&link=https://example.com/callback
Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 22
Date: date-requested
{
"message": "otp sent"
}
Request an access token
The One Time Password grant requires that all of the parameters, including client application defined parameters to be sent in the request body when requesting an access token. Use the application/x-www-form-urlencoded content type.
POST oauth2/v0/token
Post Body
| Name | Type | Format | Description |
|---|---|---|---|
client_id |
string |
UUID |
Required The client_id as defined in the SAP Concur application management system. |
client_secret |
string |
UUID |
Required The client_secret as set by the client owner in the SAP Concur application management system. |
channel_handle |
string |
- | Required The location (email address, phone number) where the one time token should be sent. |
channel_type |
string |
- | Required The type of messaging system to use. Currently only email is valid |
scope |
string |
- | The scope(s) requested by the client for the token. |
grant_type |
string |
- | Required The grant type being used, specifically for this approach: otp. |
otp |
string |
- | Required The one-time token provided as a result of the Send a one time token to the user method. |
Request
POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 437
POST BODY
client_id=your-client_id
&client_secret=your-client_secret
&channel_handle=email adress
&channel_type=valid-email
&scope=app_scope
&grant_type=otp
&otp=one-time-token
Response
HTTP/1.1 200 OK
Date: date-requested
Content-Length: 1490
Connection: keep-alive
{
"expires_in": "3600",
"scope": "app-scopes",
"token_type": "Bearer",
"access_token": "access_token",
"refresh_token": "refresh_token",
"id_token": "ocid_token",
"geolocation": "https://us.api.concursolutions.com"
}
Response Codes
HTTP Status returned by oauth2
| HTTP Status | Description |
|---|---|
| 200 | OK - Successful call, response is in body. |
| 400 | Bad Request (error, error_description, code) |
| 401 | Unauthorized (error, error_description, code) |
| 403 | Forbidden (error, error_description, code) |
| 404 | Not Found (error, error_description, code) |
| 500 | Server Error, error message is in body. |
| 503 | Server Timed Out, error message is in body. |
4xx class errors have a JSON response with the following fields
{
"code": <number>,
"error": <error>,
"error_description": <error_description>,
"geolocation": <geolocation url where user lives>
}
/authorize
If the authorization or authentication are unsuccessful, your application will receive an error code and description at the redirect_uri provided.
error_code=<>
&error_description=<>
In all cases, the friendly error description should be displayed to the user.
/token
| Code | Error | Description |
|---|---|---|
| 5 | invalid_grant |
Incorrect credentials. Please Retry |
| 10 | invalid_grant |
Account is disabled. Please contact support |
| 11 | invalid_grant |
Account is disabled. Please contact support |
| 12 | invalid_grant |
Logon Denied. Please contact support |
| 13 | invalid_grant |
Logon Denied. Please contact support |
| 14 | invalid_grant |
Account Locked. Please contact support |
| 16 | invalid_request |
user lives elsewhere |
| 19 | invalid_grant |
Incorrect credentials. Please Retry |
| 20 | invalid_grant |
Logon Denied. Please contact support (typically due to IP restriction) |
| 51 | invalid_request |
username was not supplied |
| 52 | invalid_request |
password was not supplied |
| 53 | invalid_client |
company is not enabled for this client |
| 54 | invalid_scope |
requested scope exceeds granted scope |
| 55 | invalid_request |
we don't know this email |
| 56 | invalid_request |
otp was not supplied |
| 57 | invalid_request |
channel_type missing |
| 58 | invalid_request |
channel_handle missing |
| 59 | access_denied |
client disabled |
| 60 | invalid_grant |
these are not the grants you are looking for |
| 61 | invalid_client |
client not found |
| 62 | invalid_request |
client_id was not supplied |
| 63 | invalid_request |
client_secret was not supplied |
| 64 | invalid_client |
Incorrect credentials. Please Retry |
| 65 | invalid_request |
grant_type was not supplied |
| 80 | invalid_request |
invalid channel type |
| 81 | invalid_request |
bad channel handle |
| 83 | invalid_request |
otp not found |
| 84 | invalid_request |
fact verification failed |
| 85 | invalid_request |
otp verification failed |
| 100 | invalid_request |
backend does not know about this username |
| 101 | invalid_request |
code was not supplied |
| 102 | invalid_request |
redirect_uri was not supplied |
| 103 | invalid_request |
code is bad or expired |
| 104 | invalid_grant |
redirect_uri does not match the previous grant |
| 105 | invalid_grant |
this grant was not issued to you! |
| 106 | invalid_request |
refresh_token was not supplied |
| 107 | invalid_request |
refresh disallowed for app |
| 108 | invalid_grant |
bad or expired refresh token |
| 109 | invalid_request |
loginid was not supplied |
| 115 | invalid_request |
unauthenticated client will not be issued token! |
| 117 | invalid_request |
nonce is mandatory for this response_type |
| 118 | invalid_request |
display is invalid |
| 119 | invalid_request |
prompt is invalid |
| 119 | invalid_request |
prompt must be set to consent for offline_access |
| 120 | invalid_request |
credtype is invalid |
| 121 | invalid_request |
login_type is invalid |
| 122 | invalid_request |
proxies supplied are invalid |
| 123 | invalid_request |
principal is disabled |
/otp
| Code | Error | Description |
|---|---|---|
| 16 | invalid_request |
user lives elsewhere |
| 57 | invalid_request |
channel_type was not supplied |
| 58 | invalid_request |
channel_handle was not supplied |
| 60 | invalid_grant |
these are not the grants you are looking for |
| 61 | invalid_client |
client_id is not known to us |
| 62 | invalid_request |
client_id was not supplied |
| 63 | invalid_request |
client_secret was not supplied |
| 80 | invalid_request |
invalid channel type |
| 81 | invalid_request |
bad channel handle |
| 82 | invalid_request |
the number of open otp requests has been exceeded |
Troubleshooting
In order to assist with troubleshooting, SAP Concur responds with a unique correlationId in the response header. The key to look for is correlationid. This unique code can be used during troubleshooting as it identifies the API call in the log files. You should record this information in your own API call logs as well so that you can pass this information on to the SAP Concur support team.
Example of the correlationid in the response:
< HTTP/1.1 200 OK
< Server: cnqr-papeete
< Date: Mon, 04 Dec 2017 22:07:05 GMT
< Content-Type: application/json
< Content-Length: 2897
< Connection: keep-alive
< Concur-Correlationid: 2803b8f8-a42b-43c2-a739-b8768e4759b8
Enterprise Business Applications
Only the Password Grant Type is available for obtaining company-level tokens.
- To begin the authentication flow, a Customer's SAP Concur Administrator clicks on the Connect button within the App Center listing and authorizes the partner's app. This app listing is located within customer's SAP Concur system's App Center tab.
- The SAP Concur authorization service will redirect the Admin to the Partner’s Landing Page. Partners should follow the App Center UX Guidelines to create a web page that listens for an HTTP GET request from SAP Concur.
- The redirect URI will contain an id, requestToken and userId parameters. Example:
https://{partner_redirect_URI}?id=8568a4cd-8ffc-49d6-9417-be2d69aa075f&requestToken=5l85ae5a-426f-4d6f-8af4-08648c4b696b&userId=9bdded51-00b8-4f84-8bef-6d3afe727007 - When the Partner application receives the redirect call, the Partner should strip the
idandrequestTokenvalues from the URI and use those on a Post request to the SAP Concur Authorization service to obtain the official Oauth2 Access Token and Refresh Token for the customer using the password grant. As explained in detail in this presentation, the Partner must have Data Center Geo Awareness related to the token. We currently have 3 Data Centers and the API end points change based on these Data Centers so it is imperative the proper token management is followed. Otherwise, your app will not make the correct call per Access token. - An access token is valid for only one hour. The access token should be cached in memory and discarded after use.
- After the Admin has successfully completed the login/enrollment process, the Partner should store the following elements with the customer’s profile metadata.
refresh_token: (36 characters including dashes) Valid for six months from the day and time issued.refresh_expires_in: This is Epoch time format, convert to UTC.geolocation: To be used when making API calls on behalf of the customer.id: Akasub, is the customer’s unique identifier (UUID). It can be retrieved from the following sources:- From the re-direct URI as the id element.
- By decoding the
id_tokenreturned with Access token, as thesubelement. (See https://jwt.io)
- It is highly recommended that Partners log the following elements:
userId: the user who clicked on the Connect button (returned in the re-direct URI)correlationid: SAP Concur responds with a unique code which identifies the API call in the log files. (returned in the response header). More details can be found here.
Company Level Authentication
Company
Company is a top-level principal within Concur and you would be able to obtain an access token and a refresh token on a Company's behalf just like you would be able to with a User. Only one authorization flow is currently available for obtaining tokens for a Company, which is the Password grant using a temporary auth token received from the App Center.
Obtaining A One-Time Auth Token
To begin the authentication flow for a company, one must first obtain a temporary auth token through AppCenter's interface. AppCenter will request for a temporary auth token and hand it off to the partner, who will then in turn use Password grant to exchange the temporary auth token for a full access token and refresh token for the company.
Auth tokens are valid only for 12 hours. Partners have 12 hours to exchange the auth token for a refresh and access token, and can use this auth token multiple times within the 12 hours in case of network failure.
This auth flow diagram describes this handshake:
Company Authentication Flow Sequence Diagram

AppCenter will call this endpoint to obtain an authToken. (on right)
AppCenter will call this endpoint to obtain an authToken:
(HTTP)
POST /profile-service/v1/keys/principals/<companyId>/authtoken/
Sample Curl: (on right) ```shell
(CURL)
curl -E appcenter.p12:. -H 'concur-correlationid: githbuwiki' -XPOST https://us.api.concursolutions.com/profile-service/v1/keys/principals/08BCCA1E-0D4F-4261-9F1B-F778D96617D6/authtoken/
```shell
200 OK
{
"status": "PASS",
"code": 0,
"errormsg": "",
"token": "<authToken>"
}
AppCenter redirects User to Client's auth handler URI (Connect URL) and passing in the authToken
301 Redirect https://client.app.url?id=$company_uuid&requestToken=$request_token&userID=$user_uuid
At this point, the user should be prompted to sign in to your application. If the user doesn't not have account, the user should have the ability to create one. For applications that have user read scope, the User UUID can be used to pre-populate the account creation forms. Please see the App Center User Experience guidelines for more information.
Client app calls Oauth2 password grant to get an access token for the company
| Name | Type | Format | Description |
|---|---|---|---|
client_id |
string |
UIID |
Applications client_id supplied by App Management |
client_secret |
string |
UUID |
Applications client_secret supplied by App Management |
grant_type |
string |
- | Specify which grant type you expect the oauth2 service to process. For password grant, the value is password |
username |
string |
- | specify the companyId to be used in the password grant request. The id above. |
password |
string |
- | specify the authToken to be used in the password grant request. The requestToken above. |
credtype |
string |
- | The credtype signifies to oauth2 which credential set is being submitted in the request. The value: authtoken. |
See Example Request and Response
Example Request and Response
(Request)
POST /oauth2/v0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: us.api.concursolutions.com
Connection: close
Content-Length: 175
client_id=your-client_id
&client_secret=your-client_secret
&grant_type=password
&username=<companyId>
&password=<authtoken>
&credtype=authtoken
(RESPONSE: Success)
HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 3397
Connection: Close
{
"expires_in": "3600",
"scope": "app_scopes",
"token_type": "Bearer",
"access_token": "access_token",
"refresh_token": "refresh_token",
"geolocation":"https://us.api.concursolutions.com"
}
(RESPONSE: Failure)
{
"error": "invalid_grant",
"error_description": "Incorrect Credentials. Please Retry",
"code": 5
}
Company Level Authentication - Response Codes
HTTP Status Code returned by oauth2
| HTTP Status Code | Description |
|---|---|
| 200 | OK - Successful call, response is in body. |
| 400 | Bad Request (error, error_description, code) |
| 401 | Unauthorized (error, error_description, code) |
| 403 | Forbidden (error, error_description, code) |
| 404 | Not Found (error, error_description, code) |
| 500 | Server Error, error message is in body. |
| 503 | Server Timed Out, error message is in body. |
4xx class errors have a JSON response with the following fields
{
"code": "<number>",
"error": "<error>",
"error_description": "<error_description>"
}
/token
| Code | Error | Description |
|---|---|---|
| 5 | invalid_grant |
Incorrect credentials. Please Retry |
| 10 | invalid_grant |
Account is disabled. Please contact support |
| 11 | invalid_grant |
Account is disabled. Please contact support |
| 12 | invalid_grant |
Logon Denied. Please contact support |
| 13 | invalid_grant |
Logon Denied. Please contact support |
| 14 | invalid_grant |
Account Locked. Please contact support |
| 16 | invalid_request |
user lives elsewhere |
| 19 | invalid_grant |
Incorrect credentials. Please Retry |
| 51 | invalid_request |
username was not supplied |
| 52 | invalid_request |
password was not supplied |
| 53 | invalid_client |
company is not enabled for this client |
| 54 | invalid_scope |
requested scope exceeds granted scope |
| 55 | invalid_request |
we don't know this email |
| 56 | invalid_request |
otp was not supplied |
| 57 | invalid_request |
channel_type missing |
| 58 | invalid_request |
channel_handle missing |
| 59 | access_denied |
client disabled |
| 60 | invalid_grant |
these are not the grants you are looking for |
| 61 | invalid_client |
client not found |
| 62 | invalid_request |
client_id was not supplied |
| 63 | invalid_request |
client_secret was not supplied |
| 64 | invalid_client |
Incorrect credentials. Please Retry |
| 65 | invalid_request |
grant_type was not supplied |
| 80 | invalid_request |
invalid channel type |
| 81 | invalid_request |
bad channel handle |
| 83 | invalid_request |
otp not found |
| 84 | invalid_request |
fact verification failed |
| 85 | invalid_request |
otp verification failed |
| 100 | invalid_request |
backend does not know about this username |
| 101 | invalid_request |
code was not supplied |
| 102 | invalid_request |
redirect_uri was not supplied |
| 103 | invalid_request |
code is bad or expired |
| 104 | invalid_grant |
redirect_uri does not match the previous grant |
| 105 | invalid_grant |
this grant was not issued to you! |
| 106 | invalid_request |
refresh_token was not supplied |
| 107 | invalid_request |
refresh disallowed for app |
| 108 | invalid_grant |
bad or expired refresh token |
| 109 | invalid_request |
loginid was not supplied |
| 115 | invalid_request |
unauthenticated client will not be issued token! |
| 117 | invalid_request |
nonce is mandatory for this response_type |
| 118 | invalid_request |
display is invalid |
| 119 | invalid_request |
prompt is invalid |
| 119 | invalid_request |
prompt must be set to consent for offline_access |
Migrating old tokens to new Oauth2 Bearer Tokens
Existing applications that use the Pre-2017 Authorization (Deprecated) framework need to move to support the new Oauth2 Bearer Tokens. Applications will need to migrate their existing users who already have connected to it to obtain new Oauth2 tokens without requiring users to reauthorize. This can be done by exchanging an old access token for a new refresh token.
Base URIs
When making API calls, the appropriate base URI for the user's geolocation should be used. See the Base URIs page for the full list.
Exchanging a Token
In order to support new Oauth2, applications need to exchange old access token for new accessToken and refreshToken pair. Once obtained, applications should store these refreshTokens as part of users authorization data.
The new Oauth2 accessToken has a one hour lifetime. Once expired, applications would need to call Oauth2's /v0/token endpoint using a refresh_grant, passing in the user's refreshtoken to obtain a fresh accessToken.
This is significantly different from how the deprecated /net2/Oauth2's method of handling access tokens. Partner's would have to store the new Oauth2 refreshToken instead of the old access token. Before making a call to any of Concur's new v4 APIs, it is advisable to request for a new accessToken before making the API call.
Step 1: Obtain Application Token
Clients can exchange OLD tokens for NEW Oauth2 tokens by calling the exchangeRefreshToken/me endpoint. In order to call this endpoint, you would first need to obtain an Application Token by calling the /v0/token endpoint with the client_credentials grant.
The endpoint also supports a parameter called "returnType=companyToken" This parameter allows a partner who already has what is known as a "WSAdmin" token for a client, to exchange that token for a Company level refresh token.
Step 2: Call exchangeRefreshToken
POST /appmgmt/v0/legacyApps/{OLDConsumerKey}/exchangeRefreshToken/me
If you are exchanging a WSAdmin token for a new Company level refresh token:
POST /appmgmt/v0/legacyApps/{OLDConsumerKey}/exchangeRefreshToken/me?returnType=companyToken
Request Header
| Name | Type | Format | Description |
|---|---|---|---|
Authorization |
string |
Bearer <accessToken> |
Required The NEW client_credentials accessToken. |
Request Body
| Name | Type | Format | Description |
|---|---|---|---|
token |
string |
Required The OLD refreshToken | |
secret |
string |
Required The NEW application client_secret |
Sample Curl:
curl -H 'Authorization: Bearer <accessToken>' -d '{"token": "1_oaCof444CaiNXg1FFG$Perr19qIo", "secret": "12345"}' -X POST https://us.api.concursolutions.com/appmgmt/v0/legacyApps/Bwu0mvTHtKYAnBb3Pgu9AW/exchangeRefreshToken/me
successful call, responds with
200 OK
{
"token": "8c844478-745c-4c45-adf7-1e2777a50dbf",
"created": 1479407196809,
"expired": 1494959196809,
"scopes": [
"EXPRPT",
"LIST",
"BANK",
"CCARD"
],
"context": "{\"userid\":\"7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"cid\":\"3a55c75e-ac1e-4515-845c-0a4978452828\",\"ptype\":\"user\",\"userURI\":\"https://us.api.concursolutions.com/profile-service/v1/users/7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"scope\":\"EXPRPT LIST BANK CCARD\"}"
}
Sample Curl for WSAdmin token exchange for Company level refreh token:
curl -H 'Authorization: Bearer <accessToken>' -d '{"token": "1_oaCof444CaiNXg1FFG$Perr19qIo", "secret": "12345"}' -X POST https://us.api.concursolutions.com/appmgmt/v0/legacyApps/Bwu0mvTHtKYAnBb3Pgu9AW/exchangeRefreshToken/me?returnType=companyToken
successful call, responds with
200 OK
{
"token": "8c844478-745c-4c45-adf7-1e2777a50dbf",
"created": 1479407196809,
"expired": 1494959196809,
"scopes": [
"EXPRPT",
"LIST",
"BANK",
"CCARD"
],
"context": "{\"userid\":\"7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"cid\":\"3a55c75e-ac1e-4515-845c-0a4978452828\",\"ptype\":\"company\",\"userURI\":\"https://us.api.concursolutions.com/profile-service/v1/users/7934467f-dcd1-4631-ba34-3ebd28343e8f\",\"scope\":\"EXPRPT LIST BANK CCARD\"}"
}
Step 3: Obtain New Access Token
Once you have the NEW refreshToken from the response (8c844478-745c-4c45-adf7-1e2777a50dbf) you can then proceed to call /v0/token using the refresh grant to obtain a NEW Oauth2 accessToken.
Sample Curl:
curl -X POST 'https://us.api.concursolutions.com/oauth2/v0/token' -d 'client_id=3a55c75e-ac1e-4515-845c-0a4978452828&client_secret=12345&grant_type=refresh_token&refresh_token=8c844478-745c-4c45-adf7-1e2777a50dbf'
successful call, responds with:
200 OK
{
"expires_in": 3600,
"scope": "EXPRPT LIST BANK CCARD",
"token_type": "Bearer",
"access_token": "eyJ0...demo...eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTU2MTQzNDYifQ.eyJjb25jdXIuc2NvcGVzIjpbIkVYUFJQVCIsIkxJU1QiLCJCQU5LIiwiQ0NBUkQiXSwiYXVkIjoiKiIsImNvbmN1ci5wcm9maWxlIjoiaHR0cHM6Ly91cy1ycWEzLmFwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Byb2ZpbGUvdjEvcHJpY2lwYWxzLzc5NmI0NjdmLWRjZDEtNDYzMS1iYTg1LTNlYmQyOGIzNmU4ZiIsImNvbmN1ci52ZXJzaW9uIjoyLCJjb25jdXIudHlwZSI6InVzZXIiLCJjb25jdXIuYXBwIjoiaHR0cHM6Ly91cy1ycWEzLmFwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Byb2ZpbGUvdjEvYXBwcy9lMDEwZTI1ZC1iNGNlLTRjZTMtYTdlNiLCJzdWIiOiI3OTZiNDY3Zi1kY2QxLTQ2MzEtYmE4NS0zZWJkMjhiMzZlOGYiLCJpc3MiOiJodHRwczovL3VzLXJxYTMuYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20iLCJleHAiOjE0Nzk0MTU4NjksImxlZ2FjeV9hcHBsaWNhdGlvbl9pZCI6MTUwMDA2MzY1OSwidXNlclVSSSI6Imh0dHBzOi8vdXMtcnFhMy5hcGkuY29uY3Vyc29sdXRpb25zLmNvbS9wcm9maWxlLXNlcnZpY2UvdjEvdXNlcnMvNzk2YjQ2N2YtZGNkMS00NjMxLWJhODUtM2ViZDI4YjM2ZThmIiwidXNlcnV1aWQiOiI3OTZiNDY3Zi1kY2QxLTQ2MzEtYmE4NS0zZWJkMjhiMzZlOGYiLCJuYmYiOjE0Nzk0MTIyNjksImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucyiaHR0cHM6Ly91cy1ycWEzLmFwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Byb2ZpbGUvdjEvYXBwcy9lMDEwZTI1ZC1iNGNlLTRjZTMtYTdlNC1iNjcwY2IxYWRjYjAiLCJodHRwczovL2FwaS5jb25jdXJzb2x1dGlvbnMuY29tL3Njb3BlcyI6WyJFWFBSUFQiLCJMSVNUIiwiQkFOSyIsIkNDQVJEIl0sImlhdCI6MTQ3OTQxMjI2OX0.I4EeqKZbpfFonitGBZnLBb20NwMjZNNp5e1d3-BRsepEcJSVCVYIV9HAB2EkkopvoLJsAittiZgD0iDwuh2WVgUt_c4QGzNc_-rXRtCIeKyPQRvxUZNQ7y5RTqEQFNo7hrtXiNZ-yV30zlbijP-12XU5Cu4n2VXgRKxvcCUr5j0RcovUc6O0aOR7VTzj4ZbiDdijOEtmKWGluAYyfIlz8XF2aErAB5Jff2fr9UvgHgtbleYV7eBSesvd9hJEk4S-OAtmFoJwLDECLtLcBKyeHnPEe7LmkLYShcflWG2_tYk4ysPIMG6ne5kRNxJKsDbkMItjpXhujBEGi7YIPWtFWQ",
"refresh_token": "31456dcd-b46a-4292-b2d3-f97033338487",
"geolocation": "https://us.api.concursolutions.com"
}
Migration - Response Codes
HTTP Status returned by exchangeAccessToken
| HTTP Status | Description |
|---|---|
| 200 | OK - Successful call, response is in body. |
| 400 | Bad Request - see list of responses below. |
| 404 | Not Found |
| 500 | Server Error, error message is in body. |
| 503 | Server Timed Out, error message is in body. |
exchangeAccessToken Response Codes
| CODE | Description |
|---|---|
| OK | OK - Successful call, response is in body. |
| INVALIDSCOPES | One or more scopes requested are not a subset of the allowed scopes. |
| INVALIDAPP | Application is invalid |
| INVALIDTOKEN | Bad or expired token |
| UNAUTHORIZED | Invalid credentials |
HTTP Status returned by oauth2
| HTTP Status | Description |
|---|---|
| 200 | OK - Successful call, response is in body. |
| 400 | Bad Request (error, error_description, code) |
| 401 | Unauthorized (error, error_description, code) |
| 403 | Forbidden (error, error_description, code) |
| 404 | Not Found (error, error_description, code) |
| 500 | Server Error, error message is in body. |
| 503 | Server Timed Out, error message is in body. |
4xx class errors have a JSON response with the following fields
{
"code": <number>,
"error": <error>,
"error_description": <error_description>
}
/token
| Code | Error | Description |
|---|---|---|
| 5 | invalid_grant |
Incorrect credentials. Please Retry |
| 10 | invalid_grant |
Account is disabled. Please contact support |
| 11 | invalid_grant |
Account is disabled. Please contact support |
| 12 | invalid_grant |
Logon Denied. Please contact support |
| 13 | invalid_grant |
Logon Denied. Please contact support |
| 14 | invalid_grant |
Account Locked. Please contact support |
| 16 | invalid_request |
user lives elsewhere |
| 19 | invalid_grant |
Incorrect credentials. Please Retry |
| 51 | invalid_request |
username was not supplied |
| 52 | invalid_request |
password was not supplied |
| 53 | invalid_client |
company is not enabled for this client |
| 54 | invalid_scope |
requested scope exceeds granted scope |
| 55 | invalid_request |
we don't know this email |
| 56 | invalid_request |
otp was not supplied |
| 57 | invalid_request |
channel_type missing |
| 58 | invalid_request |
channel_handle missing |
| 59 | access_denied |
client disabled |
| 60 | invalid_grant |
these are not the grants you are looking for |
| 61 | invalid_client |
client not found |
| 62 | invalid_request |
client_id was not supplied |
| 63 | invalid_request |
client_secret was not supplied |
| 64 | invalid_client |
Incorrect credentials. Please Retry |
| 65 | invalid_request |
grant_type was not supplied |
| 80 | invalid_request |
invalid channel type |
| 81 | invalid_request |
bad channel handle |
| 83 | invalid_request |
otp not found |
| 84 | invalid_request |
fact verification failed |
| 85 | invalid_request |
otp verification failed |
| 100 | invalid_request |
backend does not know about this username |
| 101 | invalid_request |
code was not supplied |
| 102 | invalid_request |
redirect_uri was not supplied |
| 103 | invalid_request |
code is bad or expired |
| 104 | invalid_grant |
redirect_uri does not match the previous grant |
| 105 | invalid_grant |
this grant was not issued to you! |
| 106 | invalid_request |
refresh_token was not supplied |
| 107 | invalid_request |
refresh disallowed for app |
| 108 | invalid_grant |
bad or expired refresh token |
| 109 | invalid_request |
loginid was not supplied |
| 115 | invalid_request |
unauthenticated client will not be issued token! |
| 117 | invalid_request |
nonce is mandatory for this response_type |
| 118 | invalid_request |
display is invalid |
| 119 | invalid_request |
prompt is invalid |
| 119 | invalid_request |
prompt must be set to consent for offline_access |
Oauth2 Migration Best Practices
Old World Authentication
- The old world authentication is a hybrid oauth2 implementation which has an endpoint that looks like this
/net2/oauth2/ - Client applications are identified by a
ConsumerKeyandSecretpair. Sometimes these are referred to asclient_idandclient_secret. - Access Tokens in the old world have a 12 months expiry period and refresh tokens live forever. This is typically not a good security practice and goes against the Oauth2 standards.
- Tokens that are being used by clients today are issued for WSADMINs, meaning all tokens have administrative access.
New World Authentication
1. Oauth2
- SAP Concur's new Oauth2 implementation follows the established Oauth2 Authorization Framework RFC : https://tools.ietf.org/html/rfc6749
- This new service has an endpoint of
/oauth2/v0/token - Unlike the old world auth, access tokens have a 1 hour expiry and refresh tokens have a 6 months expiry. This is in accordance to the best practice of using short lived tokens.
- This would mean that clients would need to perform token management.
2. Oauth2 Migration - Getting Started
- Getting clientID / clientSecret
- Work with SAP Concur's implementation team to obtain a new oauth2
client_idandclient_secretand to define the scope of client's application. - Process will take no longer than 48 hours.
- Implementation Team will respond with new
client_id,client_secret, company'srefreshTokenandexpiry date. - Client stores and configures application with this info.
- Work with SAP Concur's implementation team to obtain a new oauth2
- Client applications should store the following tokens and data in their application.
Refresh Token: This token can change although most of the time this value is the same. Client applications should treat all returned refresh tokens as new values and overwrite the stored values with the new values you get from the response.Refresh Token Expiry: This date should be checked by a daily script and ensure that a refresh_grant is made to keep the refresh token alive indefinitely. If company policy dictates that the token should be allowed to expire, then you can skip this step. Once a refresh token has expired, clients would need to contact SAP Concur's Implementation team to get a new company token.
3. Token Management
Calling APIs with
accessTokens- All APIs within SAP Concur require the calling application present an
accessTokenin the Header using the "Bearer" keyword. - Example:
curl -k -v -H "Accept: application/json" \ -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjE0NTU2MTQzNDYifQ.eyJhdWQiOiIqIiwic3ViIjoiaHR0cDovL21zcGNzcHJzcnFhLmNvbmN1ci5jb25jdXJ0ZWNoLm9yZzozMDAzL3Byb2ZpbGUtc2VydmljZS92MS91c2Vycy83NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJpc3MiOiJodHRwczovL2NvbmN1ci5jb20iLCJleHAiOjE0NzM4OTUxMjksImxlZ2FjeV9hcHBsaWNhdGlvbl9pZCI6MTUwMDA2MzY1OSwidXNlclVSSSI6Imh0dHA6Ly9tc3Bjc3Byc3JxYS5jb25jdXIuY29uY3VydGVjaC5vcmc6MzAwMy9wcm9maWxlLXNlcnZpY2UvdjEvdXNlcnMvNzYwMDlBRDMtRjc3Qi00RDk4LUEyMUEtNTUzQzlDOTE3OUYwIiwidXNlcnV1aWQiOiI3NjAwOUFEMy1GNzdCLTREOTgtQTIxQS01NTNDOUM5MTc5RjAiLCJuYmYiOjE0NzM4OTE1MjksImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vYXBwIjoiaHR0cHM6Ly9hcGkuY29uY3Vyc29sdXRpb25zLmNvbS9hcHAtbWdtdC92MC9hcHBzL2UwMTBlMjVkLWI0Y2UtNGNlMy1hN2U0LWI2NzBjYjFhZGNiMCIsImh0dHBzOi8vYXBpLmNvbmN1cnNvbHV0aW9ucy5jb20vc2NvcGVzIjpbIkNDQVJEIiwiQ09NUEQiLCJVU0VSIiwidXNlcl9yZWFkIiwiRU1FUkciLCJKT0JMT0ciLCJFUkVDUFQiLCJJVElORVIiLCJGSVNWQyIsIkxJU1QiLCJQQVNTViIsIkNPTkZJRyIsIkZPUCIsIkdIT1NUIiwiQ09OUkVRIiwiVFJJUElUIiwiQ09NUEFOWSIsInByb2ZpbGUiLCJFVlMiLCJlbWFpbCIsIlRSVlBUUyIsIkFUVEVORCIsIklOVlBPIiwiTk9USUYiLCJUUlZSRVEiLCJTVVBTVkMiLCJFWFBSUFQiLCJhZGRyZXNzIiwiRVhUUkNUIiwiUEFZQkFUIiwid3Jvbmdfc2NvcGUiLCJJTlZQTVQiLCJJTUFHRSIsIlRBWElOViIsIlJDVElNRyIsIlVOVVRYIiwiVFdTIiwiVE1DU1AiLCJCQU5LIiwiSU5WVkVOIiwib3BlbmlkIiwiTVRORyIsIklOU0dIVCIsIlRSVlBSRiIsIklOVlRWIiwiTUVESUMiLCJUU0FJIl0sImlhdCI6MTQ3Mzg5MTUyOX0.QHY4Mc5A3J981-HDv7KUdgS4tUI-qnmQAxwe9J6DHxuMmYSoGEYZ0dsnLnqc2lO2iVJK6Pg3EBZTArq8_vzV2FK7tA4-IT1eCEHo1e-RWZyWLnR7P56SvZozXpY73daovSH7572HrUm21FXcyLmdaLZyo2LfFcChaghbSCjm1Jg1duH-pLPUW4d89-_pdakmyxfV3GCm2N_XQXoRhNYAAiZcG8UfxEn3TpMHJ96F2n6keJanT_Sn2Sek_sH2EmeeCpg5-jDe0fvLvr1-gY5t0ifq8QBKWHSUUIrGbQvseD6CGzfyiFUqVypN2lukfWACR-26otN50c0OzY6kgY06RA" \ https://us.api.concursolutions.com/profile/v1/me - More documentation here: https://developer.concur.com/slate-ui/build/api-reference.html#getting-started.html
- All APIs within SAP Concur require the calling application present an
Refreshing expired
accessTokens- Since
accessTokenshave a one hour expiry, clients would need to get a newaccessTokenbefore any API call is made. - In order to obtain a new
accessToken, clients should call Oauth2 using therefresh_grantand providing the oldrefreshTokenand other additional fields. In the error handling code, clients need to handle
accessTokenexpiry errors. If theaccessTokenis expired in the middle of processing, the following should happen:- Code should call Oauth2's
refresh_grantto get a newaccessToken - Overwrite the existing
refreshTokenwith the new one. - Update
expiry dateforrefreshToken - Retry the API call.
- Code should call Oauth2's
More details about refreshing tokens here: https://developer.concur.com/slate-ui/build/api-reference.html#refresh_token
- Since
Handling errors
- There are a few error codes that client applications should be aware of.
403 Forbidden: Requesting for tokens for users who cannot be requested for. Usually for companies that are not authorized by their administrators.- The bulk of errors will be returned as 400 errors and the response contains a
codeanddescription. Client applications should look for these values to determine what to do next.
Code Desc Comment 05 Incorrect credentials. clientID / secret not correct, or authtoken/password not correct 10 Account is disabled 14 Account is locked 16 User lives elsewhere There will be a geolocation field in the response to this error message. Use this as the base URL and retry the call. 54 Invalid Scope requested scope exceeds what is permitted. - for a full list, review this doc: https://developer.concur.com/slate-ui/build/api-reference.html#response_codes
4. Old auth v.s. new auth diagram

List of Scopes for all SAP Concur APIs
Scope is a parameter as defined in the OAuth 2.0 standards (RFC6749) to enable a client to specify the scope of the access request. The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings although some implementations of scope uses a comma-delimited format. Scopes limit access for OAuth2 tokens and do not grant any additional permission beyond that which the client already has.
Scopes apply to applications only. Scopes play a crucial part in defining the ultimate access to a resource by a User.
User’s Roles / Permissions + Claims + Application Scopes
Naming Conventions
Concur services follow these standard naming conventions for scopes.
Template: {resource}.{optional subresource}.{action}
Examples: mileage.rate.read
receipts.read
List of v4 Actions
{actions} are common authorizations across resources.
| Action | Description | Examples |
|---|---|---|
read |
Read only access (GET) | receipts.read, budgetitem.read |
write |
Read AND Write access (GET, POST, UPDATE etc) | company.write, travel.receipts.write |
writeonly |
Write only access | mileage.journey.writeonly, receipts.writeonly |
delete |
Delete access | N/A |
List of v4 API Scopes
These are the list of scopes for the v4+ APIs.
| Scope | Description |
|---|---|
| budgetitem.read | Read access to budget data including fiscal calendar. |
| budgetitem.write | Read and write access to budget data including fiscal calendar. |
| company.read | Read company profile |
| company.write | Read and Write company profile |
| creditcardaccount.read | Read credit card account data |
| quickexpense.writeonly | Write quick expense |
| fiscalcalendar.read | Access to fiscal calendar |
| fiscalcalendar.write | Read and write access to fiscal calendar. |
| mileage.journey.read | Read-only access to mileage journey resources. |
| mileage.journey.writeonly | Write-only access to mileage journey resources. |
| mileage.vehicle.read | Read-only access to vehicle resources. |
| mileage.vehicle.writeonly | Write-only access to vehicle resources. |
| mileage.rate.read | Read-only access to rate configuration resources. |
| mileage.rate.writeonly | Write-only access to rate configuration resources. |
| notifications.messages.writeonly | Write messages to the notifications platform |
| openid | Return OPENID Token |
| realtimeingest.location.writeonly | Post user location object upon trip completion |
| receipts.read | Read receipts and invoices |
| receipts.write | Read and Write receipts and invoices |
| receipts.writeonly | Write only access for receipts and invoices |
| travel.receipts.read | Read requests for travel receipts |
| travel.receipts.write | Read and Write travel receipts |
| travelallowance.itinerary.read | Read only access to Itinerary data |
| travelallowance.itinerary.writeonly | Write only access to Itinerary Data |
| travelallowance.configuration.read | Read only access to Itinerary Configuration data |
| travelallowance.configuration.writeonly | Write only access to Itinerary Configuration data |
| travelallowance.itineraryresult.read | Read only access to Itinerary Result data |
| travelrequest.write | Read and write Travel Requests |
| user.read | Read user profile |
| user.write | Read and Write user profile |
| purchaserequest.write | Write only access to Purchase Requests |
| purchaserequest.read | Read only access Purchase Requests |
List of Connect API scopes
These are the list of scopes for the existing CONNECT APIs (v1.0 - v3.1)
| Scope | Description |
|---|---|
| user_read | Read user profile for old USER APIs |
| ATTEND | Attendee List - Add, Update, or Inactivate Attendees |
| CONFIG | Expense Configuration - Update Expense Feature Configuration |
| CONREQ | Connection Request - Get or update connection requests to travel reward programs |
| ERECPT | E-Receipts Provider - Post receipts and invoices, get matching facts |
| EVS | External Validation - Validate Fields Using External Systems |
| EXPRPT | Expense Report - Add, Approve, or Update Expense Reports |
| CCARD | Expense Report - Add, Approve, or Update Expense Reports |
| BANK | Expense Report - Add, Approve, or Update Expense Reports |
| EXTRCT | Extract - Request Extract of Available Data |
| FISVC | Financial Integration - Migrate transactions from Concur to external systems |
| FOP | Form of Payment - Access and update user form of payment information |
| GHOST | Form of Payment - Access and update user form of payment information |
| IMAGE | Imaging - Add or Retrieve Report and Line Item Images |
| INSGHT | Insights - Additional services marketable to users |
| INVPMT | Payment Request - Create ,Retrieve and Update for Payment Request |
| INVPO | Purchase Orders - Add or Update Purchase Orders |
| INVTV | Invoice - Tax Validation |
| INVVEN | Search, Add, Update or Delete Vendors |
| ITINER | Itinerary - Add or Update Itineraries or Bookings |
| JOBLOG | Job Log - Log Start, Detail, End and Ping |
| LIST | List Items - Add, Update, or Delete List Items |
| MTNG | Meeting - Attendee Travel Booking |
| NOTIF | Notifications - View and manage notifications |
| PAYBAT | Payment Batch - Close Batches and Request Batch Export Files |
| RCTIMG | Receipts - Add or Update Receipt and OCR Images |
| SUPSVC | Supplier Service - Get Supplier Data |
| TAXINV | Digital Tax Invoice - Get or Validate Digital Tax Invoices |
| TRVPRF | Travel Profile - Access and update user travel profile information |
| PASSV | Travel Profile - Access and update user travel profile information |
| COMPD | Travel Profile - Access and update user travel profile information |
| EMERG | Travel Profile - Access and update user travel profile information |
| TSAI | Travel Profile - Access and update user travel profile information |
| TMCSP | Travel Profile - Access and update user travel profile information |
| MEDIC | Travel Profile - Access and update user travel profile information |
| UNUTX | Travel Profile - Access and update user travel profile information |
| TRVPTS | Travel Points - Access User Balances and Post Travel Points Transactions |
| TRVREQ | Travel Request - Add, Update or Delete Travel Requests |
| TWS | Travel Approval - Approve or Reject Travel Itineraries |
| USER | Users- Add or Update User Accounts |
| COMPANY | Companies - Add or Update Company profile |
Budget v4
Budget v4 - Getting Started
Menu
Getting Started
Overview
The Budget service exposes budget and fiscal year data. Partners and clients may use the service endpoints to read and alter fiscal year, budget, budget adjustment, and budget matching configuration. Summary and detailed balance amounts are also available to read, but may not be altered via the API.
The sequence to configure budgets is to first setup the fiscal year and then the budget categories (if applicable) before creating budget items. Budget items may use budget tracking fields as filters. The budget tracking field can only be configured in the application UI. Also budget owner, approver, and budget viewer permissions have to be assigned to users prior to configuring budgets.
Process Flow

Products and Editions
- Concur Request Professional Edition
- Concur Request Standard Edition
- Concur Expense Professional Edition
- Concur Expense Standard Edition
- Concur Invoice Professional Edition
- Concur Invoice Standard Edition
Scope Usage
This API requires one or more of the following scopes:
| Name | Description | Endpoint |
|---|---|---|
budgetitem.read |
Grants read access to the budget resources. | GET Budget Category, GET Budget Item, GET Budget Tracking Fields, GET Fiscal Year, GET Valid Expense Types |
budgetitem.write |
Grants read and write access to the budget resources. | GET Budget Category, GET Budget Item, GET Budget Tracking Fields, GET Fiscal Year, GET Valid Expense Types, POST Budget Adjustment, POST Budget Category, POST Budget Item, POST Fiscal Year, DELETE Budget Category, DELETE Budget Item, DELETE Fiscal Year |
fiscalcalendar.read |
Grants read access to the fiscal calendar. | GET All Fiscal Years, GET a Fiscal Year |
fiscalcalendar.write |
Grants read and write access to the fiscal calendar. | GET All Fiscal Years, GET a Fiscal Year, POST a Fiscal Year, DELETE a Fiscal Year |
Dependencies
SAP Concur clients must purchase Budget in order to use this API.
Access Token Usage
This API supports both company level and user level access tokens. The user needs to have the Budget Administrator role in order to access the API.
Budget v4 - Fiscal Year 2020
Menu
- Getting Started
- Fiscal Year
- Budget Category
- Budget Item
- Budget Tracking Field
- Budget Adjustments
- Budget API Explorer
The Fiscal Calendar is used both for Reporting and Budget. A fiscal year can start and end at any date as long as the end date is after the start date and does not span more than two years. Fiscal years cannot overlap. Fiscal periods cannot overlap and are limited to 24 per fiscal year.
GET All Fiscal Years
Retrieve a list of all fiscal years
- Use the
lastModifiedAfterparameter if you wish to only retrieve fiscal years that were changed after a certain date. - Use the
includeRemovedparameter if you wish to retrieve all fiscal years, including those that have been deleted. Important: deleted data that is beyond the configured retention period can not be returned.
Scopes
This API call requires one of the following scopes:
budgetitem.read- Refer to Scope Usage for full details.budgetitem.write- Refer to Scope Usage for full details.fiscalyear.read- Refer to Scope Usage for full details.fiscalyear.write- Refer to Scope Usage for full details.
Request
URI
GET /budget/v4/fiscalYear
Template
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
lastModifiedAfter |
datetime |
YYYY-MM-DDTHH:MM:SS |
Use this field if you only want Fiscal Years that were changed after the supplied date. The supplied date will be interpreted in the UTC time zone. If lastModifiedAfter is not supplied, the service will return all Fiscal Years, regardless of modified date. Example: 2016-03-29T16:12:20 |
includeRemoved |
boolean |
query |
If true, the service will return all Fiscal Years, including those that were previously removed. If not supplied, this field defaults to false. |
Headers
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Payload
Example
GET https://us.api.concursolutions.com/budget/v4/fiscalYear?lastModifiedAfter=2017-02-27T12:30:00
Authorization: Bearer {token}
Content-Type: application/json
Request
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 2187
concur-correlationid: ffa4ae0a-f65c-4037-8bfb-8996c3fca28c
Response
[
{
"name":"2017",
"startDate":"2017-01-01",
"endDate":"2017-12-31",
"status":"OPEN",
"id":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
"lastModified":"2017-03-26 20:53:19",
"currentYear":false,
"monthlyFiscalPeriods":[
{
"name":"2017 - Aug",
"fiscalPeriodStatus":"OPEN",
"id":"a4e94128-c7b7-4561-a57e-1512e59e4896",
"periodType":"MONTHLY",
"startDate":"2017-08-01",
"endDate":"2017-08-31",
"spendDate":null,
"fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
"currentPeriod":false
},
{
"name":"2017 - Jan",
"fiscalPeriodStatus":"CLOSED",
"id":"ab2810f5-f045-45b0-b2b2-8e84bc978e27",
"periodType":"MONTHLY",
"startDate":"2017-01-01",
"endDate":"2017-01-30",
"spendDate":null,
"fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
"currentPeriod":false
},
{
"Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
}
],
"quarterlyFiscalPeriods":[
{"name":"2017 - Q4",
"fiscalPeriodStatus":"OPEN",
"id":"655ffe9d-caca-4f2f-a4a1-e04cfb68fd6e",
"periodType":"QUARTERLY",
"startDate":"2017-10-01",
"endDate":"2017-12-31",
"spendDate":null,
"fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
"currentPeriod":false
},
{
"Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
}
],
"yearlyFiscalPeriods":[
{
"name":"2017",
"fiscalPeriodStatus":"OPEN",
"id":"2fb8ea93-172a-47a6-9611-44eb75ad547b",
"periodType":"YEARLY",
"startDate":"2017-01-01",
"endDate":"2017-12-31",
"spendDate":null,
"fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
"currentPeriod":false
}
],
"customFiscalPeriods":[]
}
]
GET a Fiscal Year
Retrieve a single fiscal year by ID.
Scopes
This API call requires one of the following scopes:
budgetitem.read- Refer to Scope Usage for full details.budgetitem.write- Refer to Scope Usage for full details.fiscalyear.read- Refer to Scope Usage for full details.fiscalyear.write- Refer to Scope Usage for full details.
Request
URI
Template
GET /budget/v4/fiscalYear/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
uuid |
The fiscal year's key field. |
Headers
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 404 Not Found The resource could not be found or does not exist.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Payload
Example
GET https://us.api.concursolutions.com/budget/v4/fiscalYear/5e58b9b1-fed6-4d36-a5a1-a1ed325931d4
Authorization: Bearer {token}
Request
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 39216840-2808-4c49-8874-e9862d96fdb6
Response
{
"name":"2017",
"startDate":"2017-01-01",
"endDate":"2017-12-31",
"status":"OPEN",
"id":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
"lastModified":"2017-03-26 20:53:19",
"currentYear":false,
"monthlyFiscalPeriods":[
{
"name":"2017 - Aug",
"fiscalPeriodStatus":"OPEN",
"id":"a4e94128-c7b7-4561-a57e-1512e59e4896",
"periodType":"MONTHLY",
"startDate":"2017-08-01",
"endDate":"2017-08-31",
"spendDate":null,
"fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
"currentPeriod":false
},
{
"name":"2017 - Jan",
"fiscalPeriodStatus":"CLOSED",
"id":"ab2810f5-f045-45b0-b2b2-8e84bc978e27",
"periodType":"MONTHLY",
"startDate":"2017-01-01",
"endDate":"2017-01-30",
"spendDate":null,
"fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
"currentPeriod":false
},
{
"Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
}
],
"quarterlyFiscalPeriods":[
{"name":"2017 - Q4",
"fiscalPeriodStatus":"OPEN",
"id":"655ffe9d-caca-4f2f-a4a1-e04cfb68fd6e",
"periodType":"QUARTERLY",
"startDate":"2017-10-01",
"endDate":"2017-12-31",
"spendDate":null,
"fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
"currentPeriod":false
},
{
"Additional fiscal periods removed for brevity": "Additional fiscal periods removed for brevity"
}
],
"yearlyFiscalPeriods":[
{
"name":"2017",
"fiscalPeriodStatus":"OPEN",
"id":"2fb8ea93-172a-47a6-9611-44eb75ad547b",
"periodType":"YEARLY",
"startDate":"2017-01-01",
"endDate":"2017-12-31",
"spendDate":null,
"fiscalYearId":"5e58b9b1-fed6-4d36-a5a1-a1ed325931d4",
"currentPeriod":false
}
],
"customFiscalPeriods":[],
"displayName":"2017-Special"
}
POST Fiscal Year(s)
Create or update a list of one or more fiscal years.
- Fiscal years may be created for the future or the past
- Unless there is a need to do so, the client should only specify monthly fiscal periods when creating/updating a fiscal year. The system will auto-generate the quarterly and yearly fiscal periods.
Scopes
This API call requires one of the following scopes:
budgetitem.write- Refer to Scope Usage for full details.fiscalyear.write- Refer to Scope Usage for full details.
Request
URI
Template
POST /budget/v4/budgetCategory
Parameters
N/A
Headers
Payload
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server. Possibly a validation failed on the data that was sent in the payload. The response will have a list of validation errors in the body. See below for an example 400 response.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 404 Not Found The resource could not be found or does not exist.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Payload
Example
POST https://us.api.concursolutions.com/budget/v4/fiscalYear
Authorization: Bearer {token}
Request
[
{
"name":"2017-Special",
"startDate":"2017-01-01",
"endDate":"2017-03-31",
"status":"OPEN",
"monthlyFiscalPeriods":[
{
"name":"2017-Special - Jan",
"fiscalPeriodStatus":"OPEN",
"periodType":"MONTHLY",
"startDate":"2017-01-01",
"endDate":"2017-01-31"
},
{
"name":"2017-Special - Feb",
"fiscalPeriodStatus":"OPEN",
"periodType":"MONTHLY",
"startDate":"2017-02-01",
"endDate":"2017-02-28"
},
{
"name":"2017-Special - Mar",
"fiscalPeriodStatus":"OPEN",
"periodType":"MONTHLY",
"startDate":"2017-03-01",
"endDate":"2017-03-31"
}
],
"displayName":"2017-Special"
}
]
Response
Success Response
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 5c00e59f-d00c-4019-8d3d-47130d8e37b4
[
{
"name":"2017-Special",
"startDate":"2017-01-01",
"endDate":"2017-03-31",
"status":"OPEN",
"id":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"lastModified":"2018-03-26 20:54:11",
"currentYear":false,
"monthlyFiscalPeriods":[
{
"name":"2017-Special - Jan",
"fiscalPeriodStatus":"OPEN",
"periodType":"MONTHLY",
"startDate":"2017-01-01",
"endDate":"2017-01-31",
"id":"1929d1d9-6c99-4635-9272-508364193f8f",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
},
{
"name":"2017-Special - Feb",
"fiscalPeriodStatus":"OPEN",
"periodType":"MONTHLY",
"startDate":"2017-02-01",
"endDate":"2017-02-28",
"id":"41aa7452-e52a-4fd6-9c8a-5b199edeadaf",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
},
{
"name":"2017-Special - Mar",
"fiscalPeriodStatus":"OPEN",
"periodType":"MONTHLY",
"startDate":"2017-03-01",
"endDate":"2017-03-31",
"id":"6c7d0b13-96b9-4d76-a083-4d38c96144e2",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
}
],
"quarterlyFiscalPeriods":[
{
"name":"2017-Special - Q1",
"fiscalPeriodStatus":"OPEN",
"id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
"periodType":"QUARTERLY",
"startDate":"2017-01-01",
"endDate":"2017-03-31",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
}
],
"yearlyFiscalPeriods":[
{
"name":"2017-Special",
"fiscalPeriodStatus":"OPEN",
"id":"a6bede66-4f3d-412f-a620-2a073013cb2a",
"periodType":"YEARLY",
"startDate":"2017-01-01",
"endDate":"2017-03-31",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
}
],
"customFiscalPeriods":[],
"displayName":"2017-Special"
}
]
Failure Response
HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 338
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:27:05 GMT
Expires: Thu, 20 Sep 2018 15:27:05 GMT
Pragma: no-cache
concur-correlationid: cb061832-82eb-418e-a968-de6b4ce370ae
{
"status" : false,
"errorMessageList" : [
{
"errorType" : "ERROR",
"errorCode" : "BUDGET.FISCAL_YEAR_SDATE_ERROR",
"errorMessage" : "Fiscal year should have a start date"
},
{
"errorType" : "ERROR",
"errorCode" : "BUDGET.FISCAL_YEARS_HAVE_GAP",
"errorMessage" : "Fiscal years should not have gaps between them"
}
]
}
DELETE a Fiscal Year
Delete a fiscal year. Fiscal years that are in use may not be deleted.
Scopes
This API call requires one of the following scopes:
budgetitem.write- Refer to Scope Usage for full details.fiscalyear.write- Refer to Scope Usage for full details.
Request
URI
Template
DELETE /budget/v4/fiscalYear/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
uuid |
The fiscal years's key field. |
Headers
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 404 Not Found The resource could not be found or does not exist.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Example
Request
DELETE https://us.api.concursolutions.com/budget/v4/fiscalYear/a11cfc7c-967f-415f-9b30-23f8ce2dbf69
Authorization: Bearer {token}
Response
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: eb7cf20a-3481-45a5-808c-98b8ef7fe805
Fiscal Year - Schema
Get a FiscalYear
| Name | Type | Format | Description |
|---|---|---|---|
currentYear |
boolean |
- | READ ONLY True if this the current fiscal year based on the current date and time, False otherwise. |
startDate |
date |
YYYY-MM-DD |
Required The start date for this fiscal year. The distance between start date and end date may not be more than two years. |
endDate |
date |
YYYY-MM-DD |
Required The end date for this fiscal year. The distance between start date and end date may not be more than two years. |
name |
datetime |
- | Required The name of this fiscal year. Must be unique for this entity. |
status |
string |
- | Required The status of this fiscal year. Supported values: OPEN, CLOSED, REMOVED |
id |
string |
- | The budget service's key for this object. |
lastModified |
datetime |
- | READ ONLY The UTC date and time when this object was last changed. |
monthlyFiscalPeriods |
array |
fiscalPeriod |
Required The list of monthly fiscal periods in this fiscal year. Fiscal periods must complete fill the parent fiscal year with no overlaps. |
quarterlyFiscalPeriods |
array |
fiscalPeriod |
READ ONLY The list of quarterly fiscal periods in this fiscal year. If this parameter is not specified, quarterly fiscal periods are automatically generated based on the monthly fiscal periods supplied. |
yearlyFiscalPeriods |
array |
fiscalPeriod |
READ ONLY The list of yearly fiscal periods in this fiscal year. If this parameter is not specified, one period is created that fills the fiscal year. |
customFiscalPeriods |
array |
fiscalPeriod |
READ ONLY The list of custom fiscal periods in this fiscal year. Custom fiscal periods are API-only and will not display on user budget dashboards. |
openAndClosedFiscalPeriods |
array |
fiscalPeriod |
READ ONLY The list of all fiscal periods in this fiscal year, sorted by status. |
fiscalPeriods |
array |
fiscalPeriod |
READ ONLY The list of all fiscal periods in this fiscal year. |
displayName |
string |
- | READ ONLY Display name for fiscal year. For date range budget item we use this field to display. |
Get a - FiscalPeriod
| Name | Type | Format | Description |
|---|---|---|---|
currentPeriod |
boolean |
- | READ ONLY True if this the current fiscal period based on the current date and time, False otherwise. |
startDate |
date |
YYYY-MM-DD |
Required The start date for this fiscal period. Must be within the parent fiscal year. |
endDate |
date |
YYYY-MM-DD |
Required The end date for this fiscal year. Must be within the parent fiscal year. |
name |
string |
- | Required The name of this fiscal period. Must be unique for this entity. |
fiscalPeriodStatus |
string |
- | Required The status of this fiscal period. Supported values: OPEN, CLOSED, REMOVED |
periodType |
string |
- | Required The type of fiscal period. Supported values: MONTHLY, QUARTERLY, YEARLY, CUSTOM |
fiscalYearId |
string |
- | The key of the parent fiscal year for this fiscal period. |
id |
string |
- | The budget service's key for this object. |
spendDate |
date |
- | READ ONLY If the current date is after this fiscal period's start date, this field shows the current date. |
Budget v4 - Error Response
| Name | Type | Format | Description |
|---|---|---|---|
status |
boolean |
- | False if there was an error. |
errorMessageList |
array |
errorMessage |
List of all errors detected. |
Budget v4 - Error Message
| Name | Type | Format | Description |
|---|---|---|---|
errorType |
String |
- | WARNING or ERROR. |
errorCode |
String |
- | Text code for this error. |
errorMessage |
String |
- | Plain language error message. |
Response Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Allow
- RFC 7234 Cache-Control
- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7234 Expires
- RFC 7232 ETag
- RFC 7234 Pragma
- RFC 7231 Server
- RFC 7231 Vary
Budget v4 - Budget Category
Menu
This resource is used to retrieve and update budget categories which are collections of expense types used for budget matching. Each budget item header may have one Budget Category. If it does, only line items with expense types contained in that Budget Category will be accumulated to the budget.
- GET All Budget Categories
- GET a Budget Category
- POST a Budget Category
- DELETE a Budget Category
- GET All Valid Expense Types
- Schema
- Response Headers
GET All Budget Categories
Retrieve a list of all budget categories.
Scopes
This API call requires one of the following scopes:
budgetitem.read- Refer to Scope Usage for full details.budgetitem.write- Refer to Scope Usage for full details.
Request
URI
GET /budget/v4/budgetCategory
Template
Parameters
N/A
Headers
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Payload
Example
GET https://us.api.concursolutions.com/budget/v4/budgetCategory
Authorization: Bearer {token}
Content-Type: application/json
Request
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1292
concur-correlationid: 9d59b6f0-e5bd-47bf-bcad-4c3de9f5c45c
Response
[
{
"name":"Marketing and Outreach",
"description":null,
"statusType":"OPEN",
"id":"36047f6c-6cf6-443d-a952-39efb012acdb",
"expenseTypes":[
{
"featureTypeCode":"PURCHASE_REQUEST",
"expenseTypeCode":"MKTG",
"id":"f35827a8-7981-4a5b-bfc3-da7ebb4665ff",
"name":null
},
{
"featureTypeCode":"EXPENSE",
"expenseTypeCode":"SEMNR",
"id":"30f16783-e50e-4ab4-b6fb-f66cc75956f2",
"name":null
},
{
"featureTypeCode":"PURCHASE_REQUEST",
"expenseTypeCode":"ADVT",
"id":"64a04928-37b0-49c8-99e8-c346e6d47825",
"name":null
}
]
},
{
"name":"Airfare",
"description":null,
"statusType":"OPEN",
"id":"459fe79a-9b1e-4ea0-8416-19de0ff14eef",
"expenseTypes":[
{
"featureTypeCode":"EXPENSE",
"expenseTypeCode":"AIRFR",
"id":"53300041-3fb9-4a93-8cdf-327fcbe74a0c",
"name":null
},
{
"featureTypeCode":"REQUEST",
"expenseTypeCode":"AIRFR",
"id":"29278c5a-624a-4dd6-a2c1-02dd233d3fbf",
"name":null
}
]
}
]
GET a Budget Category
Retreive the details of a single budget category.
Scopes
This API call requires one of the following scopes:
budgetitem.read- Refer to Scope Usage for full details.budgetitem.write- Refer to Scope Usage for full details.
Request
URI
Template
GET /budget/v4/budgetCategory/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
| id | string |
uuid |
The budget category's key field. |
Headers
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 404 Not Found The resource could not be found or does not exist.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Payload
Example
GET https://us.api.concursolutions.com/budget/v4/budgetCategory/36047f6c-6cf6-443d-a952-39efb012acdb
Authorization: Bearer {token}
Content-Type: application/json
Request
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 642
concur-correlationid: f7b1a193-46cc-4784-9c6f-d8e1e47ecaa1
Response
{
"name":"Marketing and Outreach",
"description":null,
"statusType":"OPEN",
"id":"36047f6c-6cf6-443d-a952-39efb012acdb",
"expenseTypes":[
{
"featureTypeCode":"PURCHASE_REQUEST",
"expenseTypeCode":"MKTG",
"id":"f35827a8-7981-4a5b-bfc3-da7ebb4665ff",
"name":null
},
{
"featureTypeCode":"EXPENSE",
"expenseTypeCode":"SEMNR",
"id":"30f16783-e50e-4ab4-b6fb-f66cc75956f2",
"name":null
},
{
"featureTypeCode":"PURCHASE_REQUEST",
"expenseTypeCode":"ADVT",
"id":"64a04928-37b0-49c8-99e8-c346e6d47825",
"name":null
}
]
}
POST a Budget Category
Save a new budget category or update an existing budget category.
- When adding expense types to a budget category, only the feature type code and expense type code are needed.
- Since Expense Report expense types are shared with Request and Payment Request (Invoice) expense types are shared with Purchase Request, only EXPENSE and PAYMENT_REQUEST expense types must be supplied. The types will be copied to REQUEST and PURCHASE REQUEST automatically.
- If an expense type is supplied but the feature is not enabled, it will have no effect. For example, an Invoice-Maintenance expense type can be added to a Budget Category if Invoice is not enabled for Budget--it will not change how spending is assigned to budgets.
Scopes
budgetitem.write - Refer to Scope Usage for full details.
Request
URI
Template
POST /budget/v4/budgetCategory
Parameters
N/A
Headers
Payload
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server. Possibly a validation failed on the data that was sent in the payload. The response will have a list of validation errors in the body. See below for an example 400 response.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 404 Not Found The resource could not be found or does not exist.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Payload
Budget Category or Error Response
Example
POST https://us.api.concursolutions.com/budget/v4/budgetCategory
Authorization: Bearer {token}
Content-Type: application/json
Request
{
"name": "Advertising Category",
"description": "Advertising",
"expenseTypes": [
{
"featureTypeCode": "EXPENSE",
"expenseTypeCode": "ADVT"
},
{
"featureTypeCode": "PAYMENT_REQUEST",
"expenseTypeCode": "ADVT"
}
],
"statusType": "OPEN"
}
Response
Success Response
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 5c00e59f-d00c-4019-8d3d-47130d8e37b4
{
"name": "Advertising Category",
"description": "Advertising",
"id": "d9fd5191-7016-4f50-a6c8-4770bddc01d8",
"statusType": "OPEN",
"expenseTypes": [
{
"id": "e1dd44da-25b4-4180-8d89-00f3a8d8cf4e",
"featureTypeCode": "EXPENSE",
"expenseTypeCode": "ADVT",
"name": null
},
{
"id": "67253ac1-77e0-4d61-a478-0d194611b320",
"featureTypeCode": "PAYMENT_REQUEST",
"expenseTypeCode": "ADVT",
"name": null
}
]
}
Failure Response
HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 338
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:27:05 GMT
Expires: Thu, 20 Sep 2018 15:27:05 GMT
Pragma: no-cache
concur-correlationid: 44adb686-a624-4ee5-b618-e4ea31a95bec
{
"status" : false,
"errorMessageList" : [
{
"errorType" : "ERROR",
"errorCode" : "BUDGET.BUDGET_CATEGORY_NAME_REQUIRED",
"errorMessage" : "Budget category name is required"
},
{
"errorType" : "ERROR",
"errorCode" : "BUDGET.BUDGET_CATEGORY_NAME_UNIQUE_ERROR",
"errorMessage" : "Budget category must have a unique name"
}
]
}
DELETE a Budget Category
Delete a budget category. Budget categories that are in use by budget items may not be deleted.
Scopes
budgetitem.write - Refer to Scope Usage for full details.
Request
URI
DELETE /budget/v4/budgetCategory/{id}
Template
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
| id | string |
uuid |
The budget category's key field. |
Headers
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 404 Not Found The resource could not be found or does not exist.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Example
Request
DELETE https://us.api.concursolutions.com/budget/v4/budgetCategory/a5e00b3f-b941-4522-8b0e-07412fb2cc7c
Authorization: Bearer {token}
Content-Type: application/json
Response
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 0
concur-correlationid: 39216840-2808-4c49-8874-e9862d96fdb6
GET All Valid Expense Types
Retrieve a list of all possible expense types that may be used in a budget category.
- The list for REQUEST expense types is identical to the list for EXPENSE expense types and similarly PURCHASE_REQUEST is identical to PAYMENT_REQUEST. Due to response size and performance concerns, only EXPENSE and PAYMENT_REQUEST are returned and the caller should assume that identical expense types exist for REQUEST and PURCHASE_REQUEST.
Scopes
This API call requires one of the following scopes:
budgetitem.read- Refer to Scope Usage for full details.budgetitem.write- Refer to Scope Usage for full details.
Request
URI
Template
GET /budget/v4/budgetCategory/expenseTypes
Parameters
N/A
Headers
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Payload
Example
Request
GET https://us.api.concursolutions.com/budget/v4/budgetCategory/expenseTypes
Authorization: Bearer {token}
Accept: application/json
Response
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 367
concur-correlationid: 7afa7091-bc4e-4408-8248-a67f9e24a023
[
{
"featureTypeCode":"EXPENSE",
"expenseTypeCode":"AIRFR",
"id":null,
"name":"Airfare"
},
{
"featureTypeCode":"EXPENSE",
"expenseTypeCode":"AIRTX",
"id":null,
"name":"Airfare Ticket Tax"
},
{
"featureTypeCode":"PAYMENT_REQUEST",
"expenseTypeCode":"CATER",
"id":null,
"name":"Catering"
}
]
Budget Category - Schema
BudgetCategory
| Name | Type | Format | Description |
|---|---|---|---|
description |
string |
- | The friendly name for this category. |
expenseTypes |
array |
expenseType |
Required The list of expense types that this budget category matches. |
name |
string |
- | Required The admin-facing name for this category. |
statusType |
string |
- | The status of this budget category. Supported values: OPEN, REMOVED |
id |
string |
- | The unique identifier for the budget category. |
ExpenseType
| Name | Type | Format | Description |
|---|---|---|---|
featureTypeCode |
string |
- | Required The type of feature that this expense type applies to: Purchase Request, Payment Request (Invoice), Expense, or Travel Authorization. Supported values: PURCHASE_REQUEST, PAYMENT_REQUEST, EXPENSE, REQUEST |
expenseTypeCode |
string |
- | Required The alphanumeric code that describes an expense type (Example: MEALS, AC_CATER). Any string may be used, but only expense type codes returned by GET /budgetCategory/expenseType will behave properly in the SAP Concur UI. |
name |
string |
- | READ ONLY The name for this expense type if it maps to an expense type set up in SAP Concur. |
id |
string |
- | The budget service's key for this object. If this field is not supplied, the service will use an existing expense type entry if one exists. |
Budget Category - Error Response
| Name | Type | Format | Description |
|---|---|---|---|
status |
boolean |
- | False if there was an error. |
errorMessageList |
array |
errorMessage |
List of all errors detected. |
Budget Category - Error Message
| Name | Type | Format | Description |
|---|---|---|---|
errorType |
String |
- | WARNING or ERROR. |
errorCode |
String |
- | Text code for this error. |
errorMessage |
String |
- | Plain language error message. |
Budget Category - Response Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Allow
- RFC 7234 Cache-Control
- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7234 Expires
- RFC 7232 ETag
- RFC 7234 Pragma
- RFC 7231 Server
- RFC 7231 Vary
Budget v4 - Budget Item
Menu
Budget Item
This resource is used to retrieve and update information about a budget that spans a single fiscal year. Each budget has multiple details that correspond to fiscal periods - months, quarters, or a single period for a yearly budget.
- GET All Budget Items
- GET a Budget Item
- POST a Budget Item
- DELETE a Budget Item
- Schema
- Response Headers
GET All Budget Items
Retrieve all budget items in groups of up to 50 items. Due to response size and performance considerations, this endpoint does not return budgetItemDetails. Use the GET a Budget Item to retrieve all the details for a single budget.
Scopes
This API call requires one of the following scopes:
budgetitem.read- Refer to Scope Usage for full details.budgetitem.write- Refer to Scope Usage for full details.
Request
URI
GET /budget/v4/budgetItemHeader
Template
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
adminView |
boolean |
query |
If true, returns all budgets for this entity, if false, returns only the budgets owned by the current user. Default: false |
offset |
integer |
query |
The start of the page offset. Default: 0 |
Headers
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Payload
Example
GET https://us.api.concursolutions.com/budget/v4/budgetItemHeader
Authorization: Bearer {token}
Accept: application/json
Request
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: dd6cee88-b725-4c06-9ee9-0ca4ae4f16b2
Response
{
"totalRows":122,"offset":0,"limit":50,
"budgetItemHeaders":[
{
"name":"Marketing-US-Jean Normandy",
"isTest":false,
"budgetItemStatusType":"OPEN",
"description":"Marketing-US",
"id":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"costObjects":[
{
"code": "6",
"fieldDefinitionId": "86eee673-3d81-49c2-966a-b63c7a9302e2",
"value": "2",
"listKey": "1334",
"operator": "EQUAL",
"displayName": "Country Code"
}
],
"periodType":"YEARLY",
"active":true,
"owned":false,
"budgetAmounts":{
"pendingAmount":1178.37697091,
"unExpensedAmount":2310.73578092,
"spendAmount":35.78378912,
"adjustedBudgetAmount": 0,
"availableAmount":8785.83923997,
"unExpensedSettings":null,
"threshold":"UNDER",
"consumedPercent":12
},
"createdDate": "2019-06-26T17:49:53.102Z",
"budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"budgetName":"Marketing-US-Jean Normandy",
"currencyCode":"EUR",
"annualBudget":10000.00000000,
"budgetCategory":{
"name":"airfare",
"description":null,
"statusType":"OPEN",
"id":"27451c2d-9121-44bd-b4b0-f2119d2071c7"
},
"owner":{
"externalUserCUUID":"8002250890004822936",
"employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
"id":"f779261d-77ce-4123-b739-d842ef6f104d",
"name":"Jean Normandy",
"email":"jean.normandy@xyz.com",
"employeeId":"jean.normandy"
},
"budgetApprovers":[
{
"externalUserCUUID":"8002250890004822936",
"employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
"id":"f779261d-77ce-4123-b739-d842ef6f104d",
"name":"Jean Normandy",
"email":"jean.normandy@xyz.com",
"employeeId":"jean.normandy"
}
],
"budgetManagers":[
{
"externalUserCUUID":"1563846384638464842",
"employeeUuid":"13a13839-68d6-4ee8-90e9-58604278aa8f",
"id":"e2bae688-e000-464a-8728-e1362c94f172",
"name":"Walter Gupta",
"email":"walter.gupta@xyz.com",
"employeeId":"walter.gupta"
}
],
"budgetType": "PERSONAL_USE",
"budgetViewers":[
{
"externalUserCUUID":"5005380230004873464",
"employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
"id":"7ce7dfe0-6168-4b93-bb35-386bf023acc6",
"name":"Dan Lee",
"email":"dan.lee@xyz.com",
"employeeId":"dan.lee"
}
],
"dateRange": null,
"fiscalYear":{
"name":"2017",
"displayName":"2017",
"startDate":"2017-01-01",
"endDate":"2017-12-31",
"status":"OPEN",
"id":"a4f9d57f-14ac-4f03-b5aa-4256e5cff790",
"lastModified":"2017-03-26 20:53:19",
"currentYear":false
}
},
{"Additional budget item headers removed for brevity":"Additional budget items headers removed for brevity"}
],
"href":"https://us.api.concursolutions.com/budget/v1.1/budgetItemHeader/?offset=0",
"next":{
"href":"http://budget-service-rqa3-budget.us-west-2.nonprod.cnqr.delivery/budget/v1.1/budgetItemHeader/?adminView=true&offset=50"
},
"previous":null
}
GET a Budget Item
Retrieve the details of a single budget item.
Scopes
This API call requires one of the following scopes:
budgetitem.read- Refer to Scope Usage for full details.budgetitem.write- Refer to Scope Usage for full details.
Request
URI
GET /budget/v4/budgetItemHeader/{id}
Template
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
uuid |
The budget item header's key field. |
Headers
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 404 Not Found The resource could not be found or does not exist.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Payload
Example
GET https://us.api.concursolutions.com/budget/v4/budgetItemHeader/72eee673-3d81-49c2-966a-b63c7a9302e6
Authorization: Bearer {token}
Request
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 1270
concur-correlationid: 918cfb55-06a1-47da-8ef1-774a45427af9
Response
{
"name":"Marketing-US-Jean Normandy",
"isTest":false,
"budgetItemStatusType":"OPEN",
"description":"Marketing-US",
"id":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"costObjects":[
{
"code": "6",
"fieldDefinitionId": "86eee673-3d81-49c2-966a-b63c7a9302e2",
"value": "2",
"listKey": "1334",
"operator": "EQUAL",
"displayName": "Country Code"
}
],
"periodType":"QUARTERLY",
"active":true,
"owned":false,
"budgetAmounts":{
"pendingAmount":6870.48165307,
"unExpensedAmount":102126.89000000,
"spendAmount":764.86966050,
"adjustedBudgetAmount": 0,
"availableAmount":2364.64868643,
"unExpensedSettings":null,
"threshold":"UNDER",
"consumedPercent":76
},
"createdDate": "2019-06-26T17:49:53.102Z",
"currencyCode":"EUR",
"annualBudget":10000.00000000,
"budgetCategory":null,
"owner":{
"externalUserCUUID":"8002250890004822936",
"employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
"id":"f779261d-77ce-4123-b739-d842ef6f104d",
"name":"Jean Normandy",
"email":"jean.normandy@xyz.com",
"employeeId":"jean.normandy"
},
"budgetApprovers":[
{
"externalUserCUUID":"8002250890004822936",
"employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
"id":"f779261d-77ce-4123-b739-d842ef6f104d",
"name":"Jean Normandy",
"email":"jean.normandy@xyz.com",
"employeeId":"jean.normandy"
}
],
"budgetManagers":[
{
"externalUserCUUID":"1563846384638464842",
"employeeUuid":"13a13839-68d6-4ee8-90e9-58604278aa8f",
"id":"e2bae688-e000-464a-8728-e1362c94f172",
"name":"Walter Gupta",
"email":"walter.gupta@xyz.com",
"employeeId":"walter.gupta"
}
],
"budgetType": "PERSONAL_USE",
"budgetViewers":[
{
"externalUserCUUID":"5005380230004873464",
"employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
"id":"7ce7dfe0-6168-4b93-bb35-386bf023acc6",
"name":"Dan Lee",
"email":"dan.lee@xyz.com",
"employeeId":"dan.lee"
}
],
"budgetItemDetails":[
{
"budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"budgetName":"Marketing-US-Jean Normandy",
"currencyCode":"USD",
"amount":2500.00000000,
"id":"4c165d40-804f-4aaa-b900-a46538537f6a",
"budgetItemDetailStatusType":"OPEN",
"budgetAmounts":{
"pendingAmount":6870.48165307,
"unExpensedAmount":102126.89000000,
"spendAmount":764.86966050,
"adjustedBudgetAmount": 0,
"availableAmount":-5135.35131357,
"unExpensedSettings":null,
"consumedPercent":305,
"threshold":"OVER"
},
"detailDashboardBudgetItemAdjustmentDTOs": [
{
"adjustmentType": "BUDGET_BALANCE",
"amount": 0,
"amountType": "QUICK_EXPENSE",
"description": "string",
"transactionDate": "2019-06-26"
}
],
"fiscalPeriod":{
"name":"2017 - Q1",
"fiscalPeriodStatus":"OPEN",
"id":"b9659f8a-4e74-4531-9e23-1222ab1507f2",
"periodType":"QUARTERLY",
"startDate":"2017-01-01",
"endDate":"2017-03-31",
"spendDate":null,
"fiscalYearId":"bcb41c95-2d53-4a1a-830f-7c6b01fa79da",
"currentPeriod":false
},
"budgetItemBalances":[
{
"featureTypeCode":"PURCHASE_REQUEST",
"featureTypeSubCode":"NONE",
"workflowState":"SUBMITTED",
"amount":6870.48165307,
"id":"11cb732e-cbc4-41cb-82be-162d632d5499"
},
{
"featureTypeCode":"EXPENSE",
"featureTypeSubCode":"NONE",
"workflowState":"PAID",
"amount":764.86966050,
"id":"0f09cc65-b879-4969-a8a1-9dd52c96486d"
},
{
"featureTypeCode":"EXPENSE",
"featureTypeSubCode":"ERECEIPTS",
"workflowState":"UNSUBMITTED",
"amount":102126.89000000,
"id":"27c49c8a-c24d-42eb-b089-84268350ae03"
}
]
},
{
"budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"budgetName":"Marketing-US-Jean Normandy",
"currencyCode":"EUR",
"amount":2500.00000000,
"id":"0a2dc181-389e-4c85-bb57-e4f1a11ace4e",
"budgetItemDetailStatusType":"OPEN",
"budgetAmounts":{
"pendingAmount":0,
"unExpensedAmount":0,
"spendAmount":0,
"adjustedBudgetAmount": 0,
"availableAmount":2500.00000000,
"unExpensedSettings":null,
"consumedPercent":0,
"threshold":"UNDER"
},
"detailDashboardBudgetItemAdjustmentDTOs": [
{
"adjustmentType": "BUDGET_BALANCE",
"amount": 0,
"amountType": "QUICK_EXPENSE",
"description": "string",
"transactionDate": "2019-06-26"
}
],
"fiscalPeriod":{
"name":"2017 - Q2",
"fiscalPeriodStatus":"OPEN",
"id":"590d4e22-40be-43cc-ac1b-01b0d0263e19",
"periodType":"QUARTERLY",
"startDate":"2017-04-01",
"endDate":"2017-06-30",
"spendDate":null,
"fiscalYearId":"bcb41c95-2d53-4a1a-830f-7c6b01fa79da",
"currentPeriod":true
},
"budgetItemBalances":[]
},
{
"Additional budget item details removed for brevity": "Additional budget item details removed for brevity"
}
],
"dateRange": null,
"fiscalYear":{
"name":"2017",
"displayName":"2017",
"startDate":"2017-01-01",
"endDate":"2017-12-31",
"status":"OPEN",
"id":"a4f9d57f-14ac-4f03-b5aa-4256e5cff790",
"lastModified":"2017-03-26 20:53:19",
"currentYear":false,
"monthlyFiscalPeriods":[
{
"name":"2017-Special - Jan",
"fiscalPeriodStatus":"OPEN",
"periodType":"MONTHLY",
"startDate":"2017-01-01",
"endDate":"2017-01-31",
"id":"1929d1d9-6c99-4635-9272-508364193f8f",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
},
{
"name":"2017-Special - Feb",
"fiscalPeriodStatus":"OPEN",
"periodType":"MONTHLY",
"startDate":"2017-02-01",
"endDate":"2017-02-28",
"id":"41aa7452-e52a-4fd6-9c8a-5b199edeadaf",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
},
{
"name":"2017-Special - Mar",
"fiscalPeriodStatus":"OPEN",
"periodType":"MONTHLY",
"startDate":"2017-03-01",
"endDate":"2017-03-31",
"id":"6c7d0b13-96b9-4d76-a083-4d38c96144e2",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
}
],
"quarterlyFiscalPeriods":[
{
"name":"2017-Special - Q1",
"fiscalPeriodStatus":"OPEN",
"id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
"periodType":"QUARTERLY",
"startDate":"2017-01-01",
"endDate":"2017-03-31",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
},
{
"name":"2017-Special - Q2",
"fiscalPeriodStatus":"OPEN",
"id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
"periodType":"QUARTERLY",
"startDate":"2017-04-01",
"endDate":"2017-06-30",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
},
{
"name":"2017-Special - Q3",
"fiscalPeriodStatus":"OPEN",
"id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
"periodType":"QUARTERLY",
"startDate":"2017-07-01",
"endDate":"2017-09-30",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
},
{
"name":"2017-Special - Q4",
"fiscalPeriodStatus":"OPEN",
"id":"5ce25dfd-8b2b-4fea-91eb-f8f9ad0bb896 ",
"periodType":"QUARTERLY",
"startDate":"2017-10-01",
"endDate":"2017-12-31",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
}
],
"yearlyFiscalPeriods":[
{
"name":"2017-Special",
"fiscalPeriodStatus":"OPEN",
"id":"a6bede66-4f3d-412f-a620-2a073013cb2a",
"periodType":"YEARLY",
"startDate":"2017-01-01",
"endDate":"2017-12-31",
"spendDate":null,
"fiscalYearId":"2edd7bd4-8f10-46e5-bf52-d553f6c7df80",
"currentPeriod":false
}
],
"customFiscalPeriods":[],
}
}
POST a Budget Item
Save a new budget or update an existing budget.
Scopes
budgetitem.write - Refer to Scope Usage for full details.
Request
URI
Template
POST /budget/v4/budgetItemHeader
Parameters
N/A
Headers
Payload
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server. Possibly a validation failed on the data that was sent in the payload. The response will have a list of validation errors in the body. See below for an example 400 response.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 404 Not Found The resource could not be found or does not exist.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Payload
Budget Item Response or Error Response
Example
POST https://us.api.concursolutions.com/budget/v4/budgetItemHeader
Authorization: Bearer {token}
Request
Quarterly Budget Example
{
"name":"Marketing-US-Jean Normandy",
"isTest":false,
"budgetItemStatusType":"OPEN",
"description":"Marketing-US",
"id":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"costObjects":[
{
"fieldDefinitionId":"86eee673-3d81-49c2-966a-b63c7a9302e2",
"code": "6",
"value": "2",
"listKey": "1334",
"operator": "EQUAL",
"displayName":"Country Code"
}
],
"periodType":"QUARTERLY",
"currencyCode":"EUR",
"budgetCategory":{
"id":"27451c2d-9121-44bd-b4b0-f2119d2071c7"
},
"owner":{
"externalUserCUUID":"8002250890004822936",
"employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
"email":"jean.normandy@xyz.com",
"employeeId":"jean.normandy"
},
"budgetApprovers":[
{
"externalUserCUUID":"5005380230004873464",
"employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
"email":"dan.lee@xyz.com",
"employeeId":"dan.lee"
}
],
"budgetManagers":[
{
"externalUserCUUID":"1563846384638464842",
"employeeUuid":"13a13839-68d6-4ee8-90e9-58604278aa8f",
"email":"walter.gupta@xyz.com",
"employeeId":"walter.gupta"
}
],
"budgetType": "PERSONAL_USE",
"budgetViewers":[
{
"externalUserCUUID":"5005380230004873464",
"employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
"email":"dan.lee@xyz.com",
"employeeId":"dan.lee"
}
],
"budgetItemDetails":[
{
"budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"budgetName":"Marketing-US-Jean Normandy",
"currencyCode":"EUR",
"amount":2500.00000000,
"id":"4c165d40-804f-4aaa-b900-a46538537f6a",
"budgetItemDetailStatusType":"OPEN",
"fiscalPeriod":{
"id":"b9659f8a-4e74-4531-9e23-1222ab1507f2"
}
},
{
"budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"budgetName":"Marketing-US-Jean Normandy",
"currencyCode":"EUR",
"amount":2500.00000000,
"id":"0a2dc181-389e-4c85-bb57-e4f1a11ace4e",
"budgetItemDetailStatusType":"OPEN",
"fiscalPeriod":{
"id":"590d4e22-40be-43cc-ac1b-01b0d0263e19"
}
},
{
"budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"budgetName":"Marketing-US-Jean Normandy",
"currencyCode":"EUR",
"amount":2500.00000000,
"id":"35d7dc8a-5ec8-4d5f-ba7c-d9304f7afee3",
"budgetItemDetailStatusType":"OPEN",
"fiscalPeriod":{
"id":"09cd5be1-a21d-47f2-b6b5-8d9019709327"
}
},
{
"budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"budgetName":"Marketing-US-Jean Normandy",
"currencyCode":"EUR",
"amount":2500.00000000,
"id":"4ec30f7c-e7fa-4832-9134-85bed9a85b9c",
"budgetItemDetailStatusType":"OPEN",
"fiscalPeriod":{
"id":"c3beec03-a096-4a33-b7af-b49127742702"
}
}
],
"fiscalYear":{
"id":"a4f9d57f-14ac-4f03-b5aa-4256e5cff790"
}
}
Date Range Budget Example
{
"name":"Marketing-US-Jean Normandy Date Range",
"isTest":false,
"budgetItemStatusType":"OPEN",
"description":"Marketing-US",
"id":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"costObjects":[
{
"code": "6",
"fieldDefinitionId": "86eee673-3d81-49c2-966a-b63c7a9302e2",
"value": "2",
"listKey": "1334",
"operator": "EQUAL",
"displayName": "Country Code"
}
],
"periodType":"DATE_RANGE",
"currencyCode":"EUR",
"budgetCategory":{
"id":"27451c2d-9121-44bd-b4b0-f2119d2071c7"
},
"owner":{
"externalUserCUUID":"8002250890004822936",
"employeeUuid":"210fe25f-e326-495c-847a-de333173f616",
"email":"jean.normandy@xyz.com",
"employeeId":"jean.normandy"
},
"budgetApprovers":[
{
"externalUserCUUID":"5005380230004873464",
"employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
"email":"dan.lee@xyz.com",
"employeeId":"dan.lee"
}
],
"budgetManagers":[
{
"externalUserCUUID":"1563846384638464842",
"employeeUuid":"13a13839-68d6-4ee8-90e9-58604278aa8f",
"email":"walter.gupta@xyz.com",
"employeeId":"walter.gupta"
}
],
"budgetType": "PERSONAL_USE",
"budgetViewers":[
{
"externalUserCUUID":"5005380230004873464",
"employeeUuid":"eb6082b0-3a9a-4e79-a350-e6e067f34969",
"email":"dan.lee@xyz.com",
"employeeId":"dan.lee"
}
],
"budgetItemDetails":[
{
"budgetItemHeaderId":"72eee673-3d81-49c2-966a-b63c7a9302e6",
"budgetName":"Marketing-US-Jean Normandy",
"currencyCode":"EUR",
"amount":2500.00000000,
"id":"4c165d40-804f-4aaa-b900-a46538537f6a",
"budgetItemDetailStatusType":"OPEN",
"fiscalPeriod":{
"id":"b9659f8a-4e74-4531-9e23-1222ab1507f7"
}
}
],
"fiscalYear":{
"id":null
}
}
Response
Success Response
HTTP/1.1 200 OK
Cache-Control: max-age=604800
Content-Type: application/json
Date: Wed, 06 Jul 2020 17:33:03 GMT
Etag: "359670651"
Expires: Wed, 13 Jul 2020 17:33:03 GMT
Last-Modified: Fri, 09 Aug 2020 23:54:35 GMT
Content-Length: 97
concur-correlationid: 809a0898-e523-4114-950d-bd22705a3b25
{
"success": true,
"budgetItemHeaderId": "72eee673-3d81-49c2-966a-b63c7a9302e6"
}
Failure Response
HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 459
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:27:05 GMT
Expires: Thu, 20 Sep 2018 15:27:05 GMT
Pragma: no-cache
concur-correlationid: cea62849-02e5-4a7f-a576-68280c84bd02
{
"status" : false,
"errorMessageList" : [
{
"errorType" : "ERROR",
"errorCode" : "BUDGET.BUDGET_ITEM_NAME_REQUIRED",
"errorMessage" : "Budget item name is required"
},
{
"errorType" : "ERROR",
"errorCode" : "BUDGET.BUDGET_ITEM_NAME_ERROR",
"errorMessage" : "Budget item name should be more than 1 characters"
},
{
"errorType" : "ERROR",
"errorCode" : "BUDGET.BUDGET_ITEM_OWNER_REQUIRED",
"errorMessage" : "Budget item owner is required"
}
]
}
DELETE a Budget Item Header
Delete a budget item.
Scopes
budgetitem.write - Refer to Scope Usage for full details.
Request
URI
Template
DELETE /budget/v4/budgetItemHeader/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
The budget item header's key field. |
Headers
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 404 Not Found The resource could not be found or does not exist.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
Payload
Budget Item Response or Error Response
Example
Request
DELETE https://us.api.concursolutions.com/budget/v4/budgetItemHeader/72eee673-3d81-49c2-966a-b63c7a9302e6
Authorization: Bearer {token}
Response
HTTP/1.1 200 OK
Cache-Control: no-store
Connection: keep-alive
Content-Length: 97
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:24:27 GMT
Expires: Thu, 20 Sep 2018 15:24:27 GMT
Pragma: no-cache
Vary: Origin
concur-correlationid: 86a0d9fe-9e98-43c3-89d8-a2917dd844cb
{
"success": true,
"budgetItemHeaderId": "72eee673-3d81-49c2-966a-b63c7a9302e6"
}
Budget Item - Schema
PagedBudgetItemHeaderList
| Name | Type | Format | Description |
|---|---|---|---|
totalRows |
integer |
- | The total number of rows available. |
offset |
integer |
- | The starting row for this page of results (zero-based). |
limit |
integer |
- | The number of results returned per page. Maximum: 50 |
budgetItemHeaders |
array |
budgetItemHeader |
List of budget item headers. Each budget item header represents a single budget for a fiscal year. |
href |
string |
- | The link to this page of results. |
previous |
string |
href |
The href for the previous page of results (null if this is the first page of results). |
next |
string |
href |
The href for the next page of results (null if no results remaining). |
BudgetItemHeader
| Name | Type | Format | Description |
|---|---|---|---|
active |
boolean |
- | READ ONLY Indicates if this budget should be displayed on user screens. |
annualBudget |
decimal |
- | READ ONLY The total budget amount and accumulated balances for this budget header. |
budgetAmounts |
array |
budgetAmounts |
READ ONLY The accumulated budget amounts for this budget. |
budgetManagers |
array |
budgetPerson |
If managers exist, spend items only matches this budget if one of the managers is in the manager hierarchy of the submitter or approver for the given spend item. |
budgetApprovers |
array |
budgetPerson |
The workflow approvers for this budget. |
budgetCategory |
array |
budgetCategory |
The budget category for this budget item. If a budget category is present, spending items must match one of the expense types in the budget category in order to match this budget. |
budgetItemDetails |
array |
budgetItemDetail |
Required Specify the budget information for each fiscal period in the fiscal year. |
budgetItemStatusType |
string |
- | The status of this budget item. Supported values: OPEN, CLOSED(no spending can be attached to this budget), REMOVED |
budgetType |
string |
- | The budget type indicates if the budget item is personal or not. Supported values: PERSONAL_USE, BUDGET, RESTRICTED |
budgetViewers |
array |
budgetPerson |
The users who can view this budget. |
costObjects |
array |
budgetTrackingValue |
The cost object list for matching spending items. |
createdDate |
date |
YYYY-MM-DD |
READ ONLY The time the budget item header was created. Date in UTC. |
currencyCode |
string |
- | The 3-letter ISO 4217 currency code for the budget currency. This is the currency code of the budget amount. Spending Items are converted using yesterday's closing value. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona. |
description |
string |
- | Required The user-friendly name for this budget. This description is displayed to end users on desktop and mobile. |
dateRange |
dateRange |
- | READ ONLY Specify custom date range for budget. |
fiscalYear |
array |
fiscalYear |
Required The fiscal year for this budget. Only the ID of the fiscal year, which can be retrieved from the Fiscal Year service, is required for creating/updating a budget. |
fiscalYearId |
string |
- | The unique identifier of the fiscal year for this budget. |
id |
string |
- | The key for this object. |
isTest |
boolean |
- | The test flag for the budget item. If true, this budget will only match spending submitted by test users. |
lastModifiedDate |
dateRange |
- | READ ONLY The last time the budget item header was updated. Date in UTC. |
name |
string |
- | Required The admin-facing name for this budget. |
owned |
string |
- | READ ONLY A flag indicating if the current user is the owner of this budget. |
owner |
array |
budgetPerson |
Required The user who is ultimately responsible for this budget. |
periodType |
string |
- | READ ONLY The type of period within the fiscal year that this budget's details use. |
BudgetItemDetail
| Name | Type | Format | Description |
|---|---|---|---|
amount |
decimal |
- | Required The budget currency amount allocated to this fiscal period. May be zero. |
budgetAmounts |
array |
budgetAmounts |
READ ONLY The accumulated budget numbers for this budget. |
budgetItemBalances |
array |
budgetItemBalance |
READ ONLY Shows the break-out of budget spending by product and workflow state. |
budgetItemDetailStatusType |
string |
- | The status of this budget item. Supported values: OPEN, CLOSED(no spending can be attached to this budget), REMOVED |
currencyCode |
string |
- | The 3-letter ISO 4217 currency code for the budget currency. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona. |
budgetName |
string |
- | READ ONLY The admin-facing name of this budget. |
budgetItemHeaderId |
string |
- | READ ONLY The unique ID of the header that contains this budget item detail. |
fiscalPeriod |
fiscalPeriod |
- | Required The fiscal period for this budget amount. Only the ID of the fiscal period, which can be retrieved from the Fiscal Year service, is required for creating/updating a budget. |
detailDashboardBudgetItemAdjustmentDTOs |
array |
detailDashboardBudgetItemAdjustment |
READ ONLY List of budget adjustments. |
fiscalPeriod |
array |
fiscalPeriod |
Required The specific fiscal period when this budget amount will be used. Only the ID of the fiscal period, which can be retrieved from the Fiscal Year service, is required for creating/updating a budget. |
BudgetAmounts
| Name | Type | Format | Description |
|---|---|---|---|
adjustedBudgetAmount |
decimal |
- | READ ONLY The amount adjusted against this budget. |
availableAmount |
decimal |
- | READ ONLY The available amount accumulated against this budget. Uses budget setting to determine which amounts are included to calculate available amount. |
consumedPercent |
decimal |
- | READ ONLY The percentage of the budget that is considered used. Uses budget setting to determine which amounts to include. |
pendingAmount |
decimal |
- | READ ONLY The pending amount accumulated against this budget. |
spendAmount |
decimal |
- | READ ONLY The spent amount accumulated against this budget. |
threshold |
string |
- | READ ONLY The indicator of whether this budget is under the alert limit, equal to or over the alert limit but under the control limit, or equal to or over the control limit. Supported values: UNDER, ALERT, OVER |
unExpensedAmount |
decimal |
- | READ ONLY The amount of unexpensed items like travel bookings, quick expenses, or e-receipts. |
unExpensedSettings |
string |
- | READ ONLY The company's budget setting for unexpensed items. Applies to all budgets for the company. Supported values: SHOW_UNSUBMITTED_EXPENSES_AS_PENDING, SHOW_UNSUBMITTED_EXPENSES_BALANCE, DO_NOT_SHOW_UNSUBMITTED_EXPENSES |
BudgetPerson
Provide externalUserCUUID or email or employee ID of the user for looking up the person.
| Name | Type | Format | Description |
|---|---|---|---|
externalUserCUUID |
string |
- | The unique identifier for this user. This must match the CUUID from SAP Concur's profile service. |
name |
string |
- | READ ONLY The user's name. Provided for convenience. |
id |
string |
- | The budget service's unique identifier for this user. |
email |
string |
- | The email address of the person to lookup. |
employeeId |
string |
- | READ ONLY The employee ID of the person to lookup. |
employeeUuid |
string |
- | The unique identifier for this user. This must match the UUID from SAP Concur's profile service. |
BudgetCategory
| Name | Type | Format | Description |
|---|---|---|---|
description |
string |
- | The list of expense types that this budget category matches. |
name |
string |
- | The admin-facing name for this category. |
statusType |
string |
- | The status of this budget category. Supported values: OPEN, REMOVED |
id |
string |
- | The unique identifier for the budget category. |
ExpenseType
| Name | Type | Format | Description |
|---|---|---|---|
featureTypeCode |
string |
- | Required The product that this expense type applies to: Purchase Request, Invoice (Payment Request), Expense, or Request. Supported values: PURCHASE_REQUEST, PAYMENT_REQUEST, EXPENSE, REQUEST |
expenseTypeCode |
string |
- | Required The alphanumeric code that describes an expense type. (Example: MEALS, AC_CATER) Valid expense type codes are returned by the GET /budgetCategory/expenseType method described in the Budget Category service. |
name |
string |
- | READ ONLY The name for this expense type if it maps to an expense type set up in your SAP Concur product(s). |
id |
string |
- | The budget service's key for this object. |
BudgetTrackingValue
| Name | Type | Format | Description |
|---|---|---|---|
code |
string |
- | The code for the cost object field. This can be used instead of fieldDefinitionId and will take priority if populated. This value can be found for your budget tracking fields you have configured by using the GET All Budget Tracking Fields resource. |
value |
string |
- | The value for the cost object field. The value of this field will be ignored unless the operator field is EQUAL, NOTEQUAL, INLIST, or NOTINLIST. The value of this field can be one or more comma-separated values if the INLIST or NOTINLIST operator is chosen. |
listKey |
string |
- | When setting up the budget, specify the listKey that maps to the value of this list in the SAP Concur list service. |
operator |
string |
- | Required The comparison to use when matching values for this tracking field. Supported values: EQUAL, INLIST, ISBLANK, NOTEQUAL, NOTINLIST, ISNOTBLANK, ISTRUE, ISFALSE, ISNOTTRUE, ISNOTFALSE |
fieldDefinitionID |
string |
- | Required The budget service’s key for this object’s field definition ID. This value can be found for your budget tracking fields you have configured by using the GET All Budget TrackingFields resource. |
displayName |
string |
- | The budget field tracking name. |
BudgetItemBalance
| Name | Type | Format | Description |
|---|---|---|---|
amount |
decimal |
- | READ ONLY The balance amount. |
featureTypeCode |
string |
- | READ ONLY The product type for this balance. Supported values: REQUEST, TRAVEL, EXPENSE, PAYMENT_REQUEST |
featureTypeSubCode |
string |
- | READ ONLY The feature type sub code for this balance. Supported values: QUICK_EXPENSE, ERECEIPT, CREDIT_CARD, PERSONAL_CARD, TRIP, RECEIPT_CAPTURE, BILLING_STATEMENT, MANUAL, NONE, BUDGET_AMOUNT, SPENT_AMOUNT, PENDING_AMOUNT, PRE_AUTHORIZED, PURGE_ADJUSTMENT |
workflowState |
string |
- | READ ONLY Supported values: UNSUBMITTED, UNSUBMITTED_HELD, SUBMITTED, APPROVED, PROCESSED, PAID. |
id |
string |
- | The unique identifier for this particular budget balance bucket.. |
Budget Item - FiscalYear
| Name | Type | Format | Description |
|---|---|---|---|
currentYear |
boolean |
- | READ ONLY If true, this is the current fiscal year based on the current date and time. false, if otherwise. |
startDate |
date |
YYYY-MM-DD |
Required The start date for this fiscal year. The distance between start date and end date may not be more than two years. |
endDate |
date |
YYYY-MM-DD |
Required The end date for this fiscal year. The distance between start date and end date may not be more than two years. |
name |
datetime |
- | Required The name of this fiscal year. Must be unique for this entity. |
status |
string |
- | Required The status of this fiscal year. Supported values: OPEN, CLOSED, REMOVED |
id |
string |
- | The budget service's key for this object. |
lastModified |
datetime |
- | READ ONLY The UTC date and time when this object was last changed. |
displayName |
string |
- | READ ONLY Display name for fiscal year. For date range budget item we use this field to display. |
monthlyFiscalPeriods |
array |
fiscalPeriod |
READ ONLY The list of monthly Fiscal Periods in this Fiscal Year. Fiscal periods must complete fill the parent Fiscal Year with no overlaps. |
quarterlyFiscalPeriods |
array |
fiscalPeriod |
READ ONLY The list of quarterly Fiscal Periods in this Fiscal Year. If this parameter is not specified, quarterly Fiscal Periods are automatically generated based on the monthly Fiscal Periods supplied. |
yearlyFiscalPeriods |
array |
fiscalPeriod |
READ ONLY The list of yearly Fiscal Periods in this Fiscal Year. If this parameter is not specified, one period is created that fills the Fiscal Year. |
customFiscalPeriods |
array |
fiscalPeriod |
READ ONLY The list of custom Fiscal Periods in this Fiscal Year. Custom Fiscal Periods are API-only and will not display on user budget dashboards. |
openAndClosedFiscalPeriods |
array |
fiscalPeriod |
READ ONLY The list of all Fiscal Periods in this Fiscal Year, sorted by status. |
fiscalPeriods |
array |
fiscalPeriod |
READ ONLY The list of all Fiscal Periods in this Fiscal Year. |
displayName |
string |
- | READ ONLY Display name for fiscal year. For date range budget item we use this field to display. |
Budget Item - FiscalPeriod
| Name | Type | Format | Description |
|---|---|---|---|
currentPeriod |
boolean |
- | READ ONLY If true, this is the current fiscal period based on the current time. false, if otherwise. |
startDate |
date |
YYYY-MM-DD |
Required The start date for this fiscal period. Must be within the parent fiscal year. |
endDate |
date |
YYYY-MM-DD |
Required The end date for this fiscal year. Must be within the parent fiscal year. |
name |
string |
- | Required The name of this fiscal period. Must be unique for this entity. |
fiscalPeriodStatus |
string |
- | Required The status of this fiscal period. Supported values: OPEN, CLOSED, REMOVED |
periodType |
string |
- | Required The type of fiscal period. Supported values: MONTHLY, QUARTERLY, YEARLY, CUSTOM, DATE_RANGE |
fiscalYearId |
string |
- | The key of the parent fiscal year for this fiscal period. |
id |
string |
- | The budget service's key for this object. |
spendDate |
date |
- | READ ONLY If the current date is after this fiscal period's start date, this field shows the current date. |
DateRange
| Name | Type | Format | Description |
|---|---|---|---|
startDate |
date |
YYYY-MM-DD |
The start date for the budget. |
endDate |
date |
YYYY-MM-DD |
The end date for the budget. |
DetailDashboardBudgetItemAdjustment
| Name | Type | Format | Description |
|---|---|---|---|
adjustmentType |
string |
- | The type of adjustment being made. Only a user reference field. Supported values: BUDGET_BALANCE, FUND_TRANSFER, EXPENSE, PAYMENT_REQUEST, PURCHASE_REQUEST, REQUEST, PURGE_ADJUSTMENT |
amount |
decimal |
- | The value of the amount adjusted (+/-). |
amountType |
string |
- | The amount type of the field. Supported values: QUICK_EXPENSE, ERECEIPT, CREDIT_CARD, PERSONAL_CARD, TRIP, RECEIPT_CAPTURE, BILLING_STATEMENT, MANUAL, NONE, BUDGET_AMOUNT, SPENT_AMOUNT, PENDING_AMOUNT, PRE_AUTHORIZED, PURGE_ADJUSTMENT |
description |
string |
- | The short description of the adjustment. |
transactionDate |
date |
YYYY-MM-DD |
The transaction date of adjusted spend. Required when the adjustment is made for amount type. Supported values: SPENT_AMOUNT, PENDING_AMOUNT |
BudgetItemResponse
| Name | Type | Format | Description |
|---|---|---|---|
success |
boolean |
- | True or False for success or failure. |
budgetItemHeaderId |
guid |
- | The key of the created/updated/removed budget item header. |
Budget Item - Error Response
| Name | Type | Format | Description |
|---|---|---|---|
status |
boolean |
- | False if there was an error. |
errorMessageList |
array |
errorMessage |
List of all errors detected. |
Budget Item - Error Message
| Name | Type | Format | Description |
|---|---|---|---|
errorType |
String |
- | WARNING or ERROR. |
errorCode |
String |
- | Text code for this error. |
errorMessage |
String |
- | Plain language error message. |
Budget Item - Response Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Allow
- RFC 7234 Cache-Control
- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7234 Expires
- RFC 7232 ETag
- RFC 7234 Pragma
- RFC 7231 Server
- RFC 7231 Vary
Budget v4 - Budget Tracking
This resource is used to retrieve information about Budget's tracking fields for an entity. Every entity may have a specific set of budget tracking fields and every budget may enable any or all of the budget tracking fields. If there are tracking fields associated, the budgets get matched to the product only when the tracking field conditions are met.
GET All Budget Tracking Fields
Retrieve budget tracking fields information that is setup in budget configuration. This information returned here like the field definition ID, is needed if you will be importing budgets with tracking field values using the post budget item resource.
Scopes
This API call requires one of the following scopes:
budgetitem.read- Refer to Scope Usage for full details.budgetitem.write- Refer to Scope Usage for full details.
Request
URI
GET /budget/v4/budgetTrackingField
Template
Parameters
N/A
Headers
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server. Possibly a validation failed on the data that was sent in the payload. The response will have a list of validation errors in the body. See below for an example 400 response.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 404 Not Found The resource could not be found or does not exist.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Allow
- RFC 7234 Cache-Control
- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7234 Expires
- RFC 7232 ETag
- RFC 7234 Pragma
- RFC 7231 Server
- RFC 7231 Vary
Payload
Example
GET https://us.api.concursolutions.com/budget/v4/budgetTrackingField
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
Request
HTTP/1.1 200 OK
Cache-Control: no-store
Connection: keep-alive
Content-Length: 1371
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:24:27 GMT
Expires: Thu, 20 Sep 2018 15:24:27 GMT
Pragma: no-cache
Vary: Origin
concur-correlationid: 86a0d9fe-9e98-43c3-89d8-a2917dd844cb
Response
[
{
"budgetTrackingFieldName": "Cost Center",
"fieldType": "LIST",
"listSyncGuid": "8652CDF9C12B4051B8D180E20840CE9B",
"fieldId": "86309e0c-913c-47a5-9bcf-24a05342c718",
"budgetSequenceNumber": 2,
"connectedListSequenceNumber": 1,
"fieldDefinitionId":"19b07cff-4d36-44bd-acfe-befcfa607075"
},
{
"budgetTrackingFieldName": "Company",
"fieldType": "VARCHAR",
"listSyncGuid": null,
"fieldId": "d8f911a1-f298-4c65-b06b-710d482c9c46",
"budgetSequenceNumber": 1,
"connectedListSequenceNumber": 1,
"fieldDefinitionId":"ea2b82f3-ac18-4509-a748-842054f47f5f"
},
{
"budgetTrackingFieldName": "Department",
"fieldType": "LIST",
"listSyncGuid": "8652CDF9C12B4051B8D180E2084Q412",
"fieldId": "c4f721cb-8fc9-48cf-993e-5ea0edefcdbd",
"budgetSequenceNumber": 3,
"connectedListSequenceNumber": 1,
"fieldDefinitionId":"8b09cc4a-0274-4f2e-b223-3179f560c6bf"
},
{
"budgetTrackingFieldName": "Vendor",
"fieldType": "VARCHAR",
"listSyncGuid": null,
"fieldId": "bcc7ba39-a3a0-4267-84f4-1d5b439cce65",
"budgetSequenceNumber": 5,
"connectedListSequenceNumber": 1,
"fieldDefinitionId":"d543d38a-ef64-4585-8151-b2f909b7e2d3"
},
{
"budgetTrackingFieldName": "Region",
"fieldType": "MLIST",
"listSyncGuid": "8652CDF9C12B4051B8D180E20840CE9B",
"fieldId": "a2502b74-e3ce-4b30-a3a4-b6ceb68cf677",
"budgetSequenceNumber": 6,
"connectedListSequenceNumber": 1,
"fieldDefinitionId":"51c46189-110b-4de4-80ac-4cbae48625d6"
},
{
"budgetTrackingFieldName": "Country",
"fieldType": "VARCHAR",
"listSyncGuid": null,
"fieldId": "4ac122ad-8c0b-4076-bd41-49b09d576d5b",
"budgetSequenceNumber": 4,
"connectedListSequenceNumber": 1,
"fieldDefinitionId":"b5017eae-0b99-47df-8e0d-2f908292598a"
}
]
Budget Tracking - Schema
Budget Tracking Field
| Name | Type | Format | Description |
|---|---|---|---|
budgetTrackingFieldName |
string |
- | The budget field tracking name. |
fieldType |
string |
- | The data type of this field or field collection. Supported values: LIST, MLIST, VARCHAR |
listSyncGuid |
string |
- | If the dataType of this item is LIST or MLIST, this is the ID of the list definition from SAP Concur's list service. |
fieldId |
string |
- | The budget service's key for this object. |
budgetSequenceNumber |
integer |
- | The sequence or the order in which the budget tracking field appears in the budget UI. This value can be used instead of fieldDefinitionId when importing budgets with POST resource. The budgetSequenceNumber is the the same as the code field when importing budgets. |
connectedListSequenceNumber |
integer |
- | READ ONLY Indicates the level of the budget tracking field in a connected list. |
fieldDefinitionId |
string |
- | The budget service's key for this object's field definition ID. This value is required when using the Budget Item POST Resource to create or update a new budget using budget tracking fields. |
Budget v4 - Budget Adjustments
Menu
This resource is used to add budget adjustments. Each budget item detail may have one or more budget adjustments and adjustments can be made to manually add or subtract the budget, spent or pending balances.
Create a Budget Adjustment
Create one or more budget adjustments.
- If the rolling adjustment feature is used, all adjustments for a given month, adjustment type, amount type, budget, and description will be combined into one adjustment. See Parameters below.
- The combination of budget item name, fiscal year name, fiscal period name, and owner email determine which budget the adjustment affects. See Schema below
- The amount type determines how the adjustment affects the budget. The budget amount adjustment reduces or increases the top-line budget amount while spent and pending amounts affect the budget balances.
- Adjustments may not be deleted or updated via the API.
Scopes
budgetitem.write - Refer to Scope Usage for full details.
Request
URI
POST /budget/v4/adjustments
Template
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
useMonthlyRollingUpdate |
boolean |
query |
Required If true, all adjustments for a given month, adjustment type, amount type & description will be rolled up to one adjustment. This is useful for an automated process that makes daily or weekly updates and doesn't want to clutter end-user dashboards. |
Headers
Payload
Response
Status Codes
- 200 OK Successful call, response is in body.
- 400 Bad Request The request was determined to be invalid by the server. Possibly a validation failed on the data that was sent in the payload. The response will have a list of validation errors in the body. See below for an example 400 response.
- 403 Forbidden The user does not have the necessary permissions to perform the request.
- 404 Not Found The resource could not be found or does not exist.
- 500 Internal Server Error Error message in response body.
- 504 Gateway Timeout Error message in response body.
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Allow
- RFC 7234 Cache-Control
- RFC 7230 Content-Length
- RFC 7231 Content-Type
- RFC 7231 Date
- RFC 7234 Expires
- RFC 7232 ETag
- RFC 7234 Pragma
- RFC 7231 Server
- RFC 7231 Vary
Payload
Either "Success" or an Error Response
Example
POST https://us.api.concursolutions.com/budget/v4/adjustments?useMonthlyRollingUpdate=false
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
Request
[
{
"budgetItemName":"API Budget-Oregon",
"fiscalYearName": "2018",
"budgetOwnerEmail": "m.jones@example.com",
"fiscalPeriodName": "2018 - Q3",
"amount": 100,
"adjustmentType": "FUND_TRANSFER",
"amountType": "BUDGET_AMOUNT",
"description": "Initial July Adjustment",
"transactionDate": "2018-07-11"
},
{
"budgetItemName":"API Budget-Travel",
"fiscalYearName": "2018",
"budgetOwnerEmail": "m.jones@example.com",
"fiscalPeriodName": "2018 - Q3",
"amount": 100,
"adjustmentType": "EXPENSE",
"amountType": "SPENT_AMOUNT",
"transactionDate": "2018-07-10"
}
]
Response
Success Response
HTTP/1.1 200 OK
Cache-Control: no-store
Connection: keep-alive
Content-Length: 9
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:24:27 GMT
Expires: Thu, 20 Sep 2018 15:24:27 GMT
Pragma: no-cache
Vary: Origin
concur-correlationid: 86a0d9fe-9e98-43c3-89d8-a2917dd844cb
"Success"
Failure Response
HTTP/1.1 400 Bad Request
Cache-Control: no-store
Connection: close
Content-Length: 242
Content-Type: application/json;charset=utf-8
Date: Fri, 21 Sep 2018 15:29:05 GMT
Expires: Thu, 20 Sep 2018 15:29:05 GMT
Pragma: no-cache
concur-correlationid: 561ce34c-6542-4bae-82a2-aa6ccd8c6b22
{
"message": {
"status" : false,
"errorMessageList" : [
{
"errorType" : "ERROR",
"errorCode" : "BUDGET.BUDGET_PERIOD_REQUIRED",
"errorMessage" : "Record 1) Record 1) Budget period is missing"
}
]
}
}
Budget Adjustments - Schema
Budget Adjustment
| Name | Type | Format | Description |
|---|---|---|---|
budgetItemName |
string |
- | Required The name of the budget of the adjustment. |
fiscalYearName |
string |
- | Required The name of the budget’s fiscal year. The default name for a fiscal year is the numeric, four-digit year. Example: 2019 |
fiscalPeriodName |
string |
- | Required The specific fiscal period when this budget amount will be used. The default name for a fiscal period is: Monthly: <fiscal year name> - <three-letter month abbreviation> (Example: 2019 - Jun). Quarterly: <fiscal year name> - Q<number of quarter> (Example: 2019 - Q2). Yearly: <fiscal year name> (Example: 2019). |
budgetOwnerEmail |
string |
- | Required The user who is responsible for the budget, as configured. |
amount |
decimal |
- | Required The budget currency amount to be adjusted. The amount may be a positive or negative value but it cannot be zero. |
adjustmentType |
string |
- | Required The type of adjustment being made. Only a user reference field. Supported values: BUDGET_BALANCE, FUND_TRANSFER, EXPENSE, PAYMENT_REQUEST, PURCHASE_REQUEST, REQUEST |
amountType |
string |
- | Required The type of the budget’s balance to adjust. Affects which values in the budget are updated. Supported values: BUDGET_AMOUNT, SPENT_AMOUNT, PENDING_AMOUNT |
description |
string |
- | A user-friendly description of the adjustment. |
transactionDate |
date |
YYYY-MM-DD |
Required if amount type is either SPENT_AMOUNT or PENDING_AMOUNT The transaction date of adjusted spend. Must be within the fiscal period. |
Budget Adjustments - Error Response
| Name | Type | Format | Description |
|---|---|---|---|
status |
boolean |
- | False if there was an error. |
errorMessageList |
array |
errorMessage |
List of all errors detected. |
Budget Adjustments - Error Message
| Name | Type | Format | Description |
|---|---|---|---|
errorType |
string |
- | WARNING or ERROR. |
errorCode |
string |
- | Text code for this error. |
errorMessage |
string |
- | Plain language error message. |
Callouts
Callouts and Application Connectors
Callouts - Overview
Callouts from SAP Concur allow clients to add an interaction with an outside system to their users' SAP Concur experience. The callouts require a web application, called an application connector, which SAP Concur will contact when appropriate. Application connectors can be hosted on the client's site or on a third-party hosting site.
Third-party developers can create callouts to provide SAP Concur clients access to information systems they manage. These developers partner with SAP Concur to have their application connectors reviewed. Once reviewed, applications are available for SAP Concur clients to purchase and configure.
Partner apps that want to use callout services must have their endpoint server(s) whitelisted with SAP Concur.
The available callouts are:
- Fetch Attendee Data
- Fetch List Item
- Event Notification
- Launch External URL
Fetch Attendee and Fetch List Item send information out from SAP Concur to an application connector that interfaces with a external system. The connector runs a search on the external system. The results are then returned to SAP Concur, which presents the results to the user.
The Event Notification callout allows clients to receive notification of specific moments in the workflow of an expense report. When a report enters the desired workflow state a request is sent to the external system. The system can call into SAP Concur to get all the details of a report and perform appropriate actions.
The Launch External URL callout gives clients and developers a platform to extend the functionality of SAP Concur, providing a means to deliver custom user interactions, or access functionality found in an external system.
The client can arrange to add an Expense Entry form field that is configured to use the Launch External URL callout to a Concur Expense Entry form. Concur Expense will display this field with an attached button that launches a separate window when clicked. The window is controlled by an application connector, created by the client, a third party developer, or SAP Concur. The application connector is a web server that presents information in the window.
The application connector can access SAP Concur data through the web services, or can access data in an external system. Once the user has completed their actions in the window (such as performing a search or completing a wizard), he/she clicks a button such as "Done" that indicates he/she has concluded their work in the window. The application connector then closes the window.
The application connector can use web services to send information to SAP Concur, to update field values on the expense entry form or other form types. The application connector may send the updates before or after the user closes the window. When the user returns to SAP Concur, the page refreshes and the user sees the current values.
Callouts - Process Flow

Application Connector Management
SAP Concur administrators use the Manage Application Connectors link on the Web Services page under Administration to register, test and enable application connectors.
Specifications
Security
SAP Concur will make calls to the application connector's endpoint using SSL. During configuration, SAP Concur will connect to the application connector to validate that its hostname and access credentials are valid.
SAP Concur will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. If you are hosting the application connector, you will need to install the signed certificate before SAP Concur can access the connector.
Callouts - Authentication
Authenticating to the application connector
Expense passes credentials using HTTP Basic Auth to authenticate with the application connector. By default, these credentials are stored in the appropriate web configuration file for your platform, such as web.xml or web.config. The steps to configure Expense with the credentials are detailed below.
Managing Application Connectors
SAP Concur administrators use the Manage Application Connectors link in Web Services under Administration to register, test and enable application connectors.
User Permission
The Web Services links can be accessed by users with the following permission:
Developer Sandbox or Expense/Invoice/Travel/Travel Request Standard:
Can Administer: Users with this permission can register and modify application connectors.
Expense/Invoice/Travel/Travel Request Professional:
Web Services Administrator: Users with this permission at companies that are Development Partners can register and modify application connectors.
All Admin roles: Users with this permission at companies that are Development Partners can register and modify application connectors.
Accessing Application Connector Registration
The Manage Application Connectors link on the Web Services page is used to register, test and enable or disable application connectors. Only SAP Concur Internal staff can access the Manage Application Connectors link.
To Access Application Connector Registration:
- On the home page, select Administration Web Services. The Web Services page appears.
- Click Manage Application Connectors. The Application Connector Registration page appears.
Registering an Application Connector
Once a development partner has configured a application connector, it must be registered with SAP Concur.
To Register an Application Connector:
- On the Application Connector Registration page, click New.
In the System area, complete all of the required fields.
Field Description Name Enter the name that should appear in the list of connectors. Description Enter the description of the function of the connector, such as what back-end system it might connect to. Host Name Enter the hostname for the connector. Example: https://{servername} User Name Enter the user name required to authenticate with the host. This must be the same as the user name specified in the configuration file for the application connector. Password Enter the password required to authenticate with the host. This must be the same as the password specified in the configuration file for the application connector. Click Test Connection. SAP Concur will attempt to connect to the test connection endpoint https://(host name)/system/v1.0/testconnection, using a GET method with the supplied credentials as HTTP Basic Authentication. If you have not configured the test connection endpoint, the test will fail.
Note: A successful Test Connection request is required to set the connector to “Verified” before it can be used for any of the callout services.
In the Services section, select an outbound message or callout that the connector will interact with.
Click Configure. The Configure Service window appears.
Enter the endpoint that the SAP Concur will connect to on the host. Example: /attendee/v1.0/find
Select the Enabled check box if the endpoint is ready for use. Usually you will do this after you have implemented and tested the endpoint in your application connector.
Click Save. The service is configured for your host.
Repeat steps 4-8 for each service to configure.
Click Save.
Modifying an Application Connector Registration
Once an application connector registration has been created, the fields can be modified. Services can be enabled or disabled from the Modify page.
To Modify an Application Connector:
- On the Application Connector Registration page, select the desired registration from the list.
- Click Modify.
- Edit the system fields as necessary.
- Click Test Connection to verify your changes.
- Edit the services configurations as necessary.
- Click Save to return to the Application Connector Registration page.
Deactivating an Application Connector Registration
Application connector registrations can't be removed, but can be deactivated. Connectors are deactivated by setting all the associated services to inactive.
To Deactivate an Application Connector:
- On the Application Connector Registration page, select the desired connector.
- Click Modify.
- Select the active Service.
- Click Configure.
- Clear the Active check box.
- Click OK.
- Click Save.
Delete notification requests
Delete an event notification.
URI
https://www.concursolutions.com/api/platform/notifications/v1.0/notification/
Delete Notification - Request
Request Parameters
notificationID: The unique identifier for the notification. Required.
Example:
https://www.concursolutions.com/api/platform/notifications/v1.0/notification/{notificationID}
URI Source: The URI is returned in the NotificationUrl element of the Response for the Get Notifications by Status function.
Headers
Authorization Header
Authorization header with OAuth token for valid SAP Concur user. Required.
The OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.
Accept Header
- application/xml
- application/json
DELETE https://www.concursolutions.com/api/platform/notifications/v1.0/notification/nOB1KNTDSV0UqiYeTsy6su$praZSogRJB6 HTTP/1.1
Authorization: OAuth {access token}
XML Example Request
Delete Notification - Response
Content Types
- application/xml
- application/json
Delete Notification - Schema
The response returns an HTTP Status Code as follows:
| HTTP Code | Description |
|---|---|
| 200 Success | Notification successfully deleted. |
| 400 Bad Request | The request is malformed. Check the API document and verify the request uses the correct format. |
| 403 Forbidden | The OAuth Consumer doesn't have a required role. Check the API documentation to learn the required roles. |
Example of Successful Response
HTTPS 200 Success
Event Notification Callout
The Event Notification callout allows clients to choose to be notified through web services when certain actions take place in their SAP Concur company. If the client uses Concur Expense, the supported events are the Expense report entering the Post-Submit or Pre-Extract workflow steps. If the client uses Concur Travel Request, the supported events are the Travel Request entering the Post-Submit or Pre-Extract workflow steps. When the event happens, SAP Concur generates a notification and places it into the notification system queue. When the notification reaches the front of the queue, SAP Concur sends a request to the configured endpoint with event information.
This callout differs from the standard SAP Concur web services in the following ways:
- It uses an outbound callout where Expense calls a public facing URL provided by the application connector, which is a web server hosted by the third-party developer or client. Refer to Callouts and Application Connectors for more information.
- The application connector can also use the web services to retrieve or send SAP Concur data.
- The developer or client can configure and maintain the public web service interface (the application connector), or the connector can be maintained by SAP Concur. This guide specifies the request and response format required by SAP Concur.
- The developer or client can choose to create their own application connector using a different language, such as PHP, if preferred.
Contents
- Process Flow
- Products and Editions
- Example Use Case
- Product Restrictions
- Event Notification Process Overview
- Security
- Authentication
- Functions
Event Notifications - Process Flow

Event Notifications - Products and Editions
- Concur Expense Professional Edition
- Concur Request Professional Edition
- The SAP Concur Mobile App
Example Use Case
An example use of this callout is:
- A SAP Concur user submits an expense report, triggering an Event Notification.
- The notification is placed in a queue and processed in a first come, first served order.
- When the notification gets to the front of the queue, it is sent to the endpoint specified by the developer.
- The application connector returns the HTTP 200 status code, and the notification is removed from the queue.
- The developer uses the Report information to make the Get Expense Report Details request.
- The developer uses the additional information to validate some expense report information.
- The developer then uses the Post Expense Report Exceptions function to approve the report.
This is one use case for the Event Notification callout, however it can be used for a wide variety of requirements.
Product Restrictions
SAP Concur products are highly configurable, and not all clients will have access to all features.
Partner developers must determine which configurations are required for their solution prior to the review process.
Existing clients can work with Concur Advantage Technical Services to create custom applications that work with their configuration.
Event Notification Process Overview
The configuration process has the following steps:
Third-party developer, client or SAP Concur downloads, installs, configures, and customizes the application connector. The application connector may make requests to the inbound web services.
The developer or the SAP Concur clients registers the application connector.
Refer to Installation > Process for the detailed steps.
Once the configuration is complete, the callout uses the following process:
- The configured event occurs in SAP Concur.
- SAP Concur sends the request information to the specified endpoint for the application connector.
Event Notifications - Security
SAP Concur will make calls to the application connector's endpoint using SSL. During configuration, SAP Concur will connect to the application connector to validate that its hostname and access credentials are valid.
In the code SAP Concur provides for a sample application connector, credentials are stored in a web configuration file that varies by platform, such as web.xml or web.config. However, if you are hosting the connector, you can customize where and how the credentials are stored by customizing HTTPBasicAuth.java or Authentication.cs.
Expense or Travel Request will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. If you are hosting the application connector, you will need to install the signed certificate before SAP Concur can access the connector.
Event Notifications - Authentication
Authentication between SAP Concur and the application connector is performed using HTTP Basic Auth. By default, these credentials are stored in the appropriate web configuration file for your platform, such as web.xml or web.config. These credentials are entered in SAP Concur on the Register Application Connector page in Web Services under Administration.
Refer to the Callouts and Application Connectors page for more information.
Functions
Post Event Notification Request
Installation Process
The installation process includes installing the application connector, and registering it with SAP Concur.
- The third-party developer or client will create and install the application connector on their web site or a third party hosting site. The connector should be programmed to accept the requests from SAP Concur and provide the documented responses.
The client registers the application connector with SAP Concur:
- Log in to SAP Concur as an administrative user.
- Select Administration > Web Services.
- Click Manage Application Connectors.
- Click New.
- Fill out the fields:
Field Description Name Enter the name that should appear in the list of connectors. Description Enter the description of the function of the connector, such as what back-end system it might connect to. Host Name Enter the hostname for the connector. Example: https://{servername} User Name Enter the user name required to authenticate with the host. This must be the same as the user name specified in the configuration file for the application connector, using HTTP Basic Auth. Password Enter the password required to authenticate with the host. This must be the same as the password specified in the configuration file for the application connector, using HTTP Basic Auth. - In the Services section, select Send Notification.
- Click Configure. The Configure Service window appears.
- Enter the endpoint that SAP Concur will connect to on your server. Example: /concur/v1.0/notify
- Select the Enabled check box if the endpoint is ready for use. Usually you will do this after you have implemented and tested the endpoint in your application connector.
- In the Workflows section, select the workflow step for each expense report or travel request workflow that requires notifications.
- Click OK.
- Click Test Connection. SAP Concur will attempt to access the configured endpoint with the provided user credentials.
- Click Save. The application connector is now registered with SAP Concur and enabled.
Responses and Errors
Refer to the HTTP Status Codes page for details of the common responses and errors.
Fetch Attendee Version 2 Callout
The Concur Fetch Attendee version 2.0 callout allows clients to import attendee information from their internal system to SAP Concur when a user is adding attendees to an entry. The SAP Concur service sends the attendee search fields to an application connector, created by the client, a third-party developer, or SAP Concur. The connector is hosted by the client or third-party developer, and has access to the attendee system of record. The connector uses the attendee information sent from SAP Concur to search for all matching attendee records in the client's system. Once the connector has the list of possible matches, it sends the attendee data to SAP Concur. The user sees the list of matches and can select the appropriate attendee for the entry.
This callout differs from the standard SAP Concur web services in the following ways:
- It uses an outbound message where SAP Concur calls a public facing API endpoint provided by the application connector. Refer to Callouts > Core Concepts for more information.
- The client or third-party developers can configure and maintain the public web service interface (the application connector), or the connector can be maintained by SAP Concur. This documentation specifies the request and response format required by SAP Concur.
- Clients can either choose to create their own application connector using PHP, Java, .NET etc or can use one of SAP Concur Partner's Attendee Fetch applications.
- The client SAP Concur Administrator must select the attendee types that will use this functionality during application connector registration. Once the attendee types are selected, they will be automatically configured to not allow users to create new attendees manually.
Contents
- Process Flow
- Products and Editions
- Product Restrictions
- Callout Details
- Fetch Attendee Process Overview
- Installation Process
Fetch Attendee - Process Flow

Fetch Attendee - Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
- Expense in the SAP Mobile App
- Concur Request Professional Edition
Fetch Attendee - Product Restrictions
- SAP Concur products are highly configurable, and not all clients will have access to all features.
- Partner developers must determine which configurations are required for their solution prior to the review process.
- Existing clients can work with Concur Advantage Technical Services to create custom applications that work with their configuration.
Callout Details
Information on how to download, install, and configure the application connector is included in Callouts > Core Concepts.
Fetch Attendee Process Overview
The configuration process has the following steps:
- Client, third party developer, or SAP Concur downloads, installs, configures, and customizes the application connector.
- Optional for Professional / Premium Only: Client SAP Concur admin creates a new attendee type to use with the connector.
- Client registers the application connector, selecting the attendee types that will use the connector.
Once the configuration is complete, the callout uses the following process:
- The user selects the appropriate attendee type in the Search Attendees window.
- The user enters information into an attendee field and clicks Search.
- SAP Concur sends the attendee search field information to the application connector. This request includes all attendee fields, with any blank values formatted as an empty string.
- The application connector queries the attendee system of record and returns a list of results to SAP Concur.
NOTE: The results list is limited to 100 records. - SAP Concur displays the results in the Search Results section of the Search Attendees window.
NOTE: If the application connector does not respond or returns an error, the user is notified in a popup window within SAP Concur. SAP Concur will not resend the request unless the user manually initiates the search again. - If the user adds the attendees to the entry, the attendee information is saved in SAP Concur.
Fetch Attendee - Security
SAP Concur will make calls to the application connector's endpoint using SSL. During configuration, SAP Concur will connect to the application connector to validate that its hostname and access credentials are valid.
SAP Concur will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. You will need to install the signed certificate before SAP Concur can access the connector.
Fetch Attendee - Authentication
Authentication between SAP Concur and the application connector is performed using HTTP Basic Auth. By default, these credentials are stored in the appropriate web configuration file for your platform, such as web.xml or web.config. These credentials are entered in SAP Concur on the Register Application Connector page in Web Services under Administration.
Refer to the Installation Process for more information.
Fetch Attendee - Functions
Version 3.0: Post Attendee Search Request
Fetch Attendee - Installation Process
The installation process includes installing the application connector, and registering it with SAP Concur.
First, the client or third-party developer will create and install the application connector on their web site or a third party hosting site. The connector should be programmed to accept the requests from SAP Concur and provide the documented responses.
During installation, the client or developer will select and configure an externally available endpoint on the host server for SAP Concur to send the attendee search request to.
The client then registers the application connector with SAP Concur:
- Log in to SAP Concur as an administrative user.
- Select Administration > Web Services.
- Click Manage Application Connectors.
- Click New.
- Fill out the fields according to the Application Connector Fields table shown below.
- In the Services section, select Fetch Attendee.
- Click Configure. The Configure Service window appears.
- Enter the endpoint that the SAP Concur will connect to on your server. Example:
/attendee/v2.0/fetch. Note: The endpoint name should contain 'v2.0', otherwise the API defaults to v1.0 and returns a different set of fields. - Select the Active check box if the endpoint is ready for use. Usually you will do this after you have implemented and tested the endpoint in your application connector.
- Select the attendee types that will use the application connector. These attendee types will be automatically configured to not allow users to create new attendees manually.
- Click OK.
- Click Test Connection. SAP Concur will attempt to access the configured endpoint with the provided user credentials.
- Click Save. The application connector is now registered with SAP Concur and enabled.
Application Connector Fields
| Field | Description |
|---|---|
| Name | Enter the name that should appear in the list of connectors. |
| Description | Enter the description of the function of the connector, such as what back-end system it might connect to. |
| Host Name | Enter the hostname for the connector. Example: https://{servername} |
| User Name | Enter the user name required to authenticate with the host. This must be the same as the user name specified in the configuration file for the application connector, using HTTP Basic Auth. |
| Password | Enter the password required to authenticate with the host. This must be the same as the password specified in the configuration file for the application connector, using HTTP Basic Auth.1.0 |
SAP Concur Configuration
The SAP Concur administrator can select which attendee types use the connector when registering the application connector. These attendee types will be automatically configured to not allow users to create new attendees manually.
Professional/Premium Only: If desired, the administrator can create a new attendee type specifically for use with the connector.
Responses and Errors
Refer to the HTTP Status Codes for details of the common responses and errors.
Fetch List Callout
The Concur Fetch List callout allows clients to import list items from an internal system to Expense when a user is filling out list fields for an expense. The Expense service sends a request for list items to an application connector, created by the client, a third-party developer, or SAP Concur. The connector is hosted by the client or developer, and has access to the list item system of record. The connector uses the list information sent from Expense to search for all matching list items in the system of record. Once the connector has the list items, it sends the data to Expense. The user sees the list items and can select the appropriate item for the expense. When the user saves the expense, the list item is added to the list within Expense.
This callout differs from the inbound SAP Concur web services in the following ways:
- It uses an outbound message where Expense calls a public facing API endpoint provided by the application connector.
- The third-party developer or client can configure and maintain the public web service interface (the application connector), or the connector can be maintained by SAP Concur. This guide specifies the request and response format required by SAP Concur.
- The client Expense administrator must configure a list (most commonly a connected list), and SAP Concur must perform database configuration on the list before this service can be used.
Contents
- Process Flow
- Products and Editions
- Product Restrictions
- Fetch List Process Overview
- Security
- Authentication
- Functions
- Concur Expense Configuration
- Responses and Errors
Fetch List Callout - Process Flow

Fetch List Callout -Products and Editions
- Concur Expense Professional Edition
- The SAP Concur Mobile App
Fetch List Callout -Product Restrictions
SAP Concur products are highly configurable, and not all clients will have access to all features.
Partner developers must determine which configurations are required for their solution prior to the review process.
Existing clients can work with Concur Advantage Technical Services to create custom applications that work with their configuration.
Fetch List Callout -Process Overview
The configuration process has the following steps:
- Third-party developer, client or SAP Concur downloads, installs, configures, and customizes the application connector.
- SAP Concur registers the application connector.
- Expense Admin creates a new list in List Management.
- SAP Concur configures the list to search for external items.
- If using a connected list, Expense Admin creates a connected list definition in Forms and Fields.
Once the configuration is complete, the callout uses the following process:
- The user selects the external source list field while creating an expense entry.
- Expense sends the list field information and the item codes for the previously selected levels (for connected lists) to the application connector.
- The application connector queries the list system of record and returns the set of list items to Expense.
- Expense displays the list items in a drop down list.
- The user selects the desired list item and saves the expense.
Fetch List Callout - Security
SAP Concur will make calls to the application connector's endpoint using SSL. During configuration, SAP Concur will connect to the application connector to validate that its hostname and access credentials are valid.
In the code SAP Concur provides for a sample application connector, credentials are stored in a web configuration file that varies by platform, such as web.xml or web.config. However, if you are hosting the connector, you can customize where and how the credentials are stored by customizing HTTPBasicAuth.java or Authentication.cs.
Expense will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. You will need to install the signed certificate before SAP Concur can access the connector.
Fetch List Callout -Authentication
Authentication between SAP Concur and the application connector is performed using HTTP Basic Auth. By default, these credentials are stored in the appropriate web configuration file for your platform, such as web.xml or web.config. These credentials are entered in SAP Concur on the Register Application Connector page in Web Services under Administration.
Fetch List Callout -Functions
Concur Expense Configuration
Expense must have a list field configured to use an external source before this callout can be used. The client creates the list, SAP Concur configures it to use the external source, and the client creates the connected list definition if necessary.
Fetch List Callout - Responses and Errors
Refer to the HTTP Status Codes page for details of the common responses and errors.
Get notifications by status
Retrieves the list of event notifications that are in the supplied status.
Get notifications by status - Request
Request Parameters
status={status}
The desired status for the notification. Required. Currently supports failed.
Example:
https://www.concursolutions.com/api/platform/notifications/v1.0/notification?status={status}
Headers
Authorization Header
Authorization header with OAuth token for valid SAP Concur user. Required.
The OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.
Accept Header
- application/xml
- application/json
Content-Type Header
application/xml
Get Notifications Status - XML Example Request
GET https://www.concursolutions.com/api/platform/notifications/v1.0/notification?status=FAILED HTTP/1.1
Authorization: OAuth {access token}
Accept: application/xml
Get notifications by status - Response
Supported Content Types
- application/xml
- application/json
Get notifications by status - Schema
This request will return a NotificationsList parent element with a Notification child element for each failed notification. The Notification elements will have a Failure child element if the notification is failed.
Failure Elements
| Element | Description |
|---|---|
| Context | Message that the callout can use to provide the developer some context for the callout. |
| EventDateTime | When the event happened. Format: YYYY-MM-DD:HH:MM:SS |
| EventType | The event that triggered the callout. |
| NotificationURL | The URL the developer calls to delete a failed notification. |
| ObjectType | The type of object that triggered the notification. |
| ObjectURI | The URI for the object. The developer can use the appropriate GET function for the Object Type. |
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Length: 626
Content-Type: application/xml
<?xml version="1.0" encoding="utf-8"?>
<NotificationList xmlns="http://www.concursolutions.com/api/notification/2012/06" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Notification>
<Context i:nil="true" />
<EventDateTime>2012-11-14T19:45:25</EventDateTime>
<EventType>Report Entered Expense Report Workflow Step - REPORT SUBMITTED</EventType>
<NotificationURI>https://www.concursolutions.com/api/platform/notifications/v1.0/notification/nOB1KNTDSWUcJPMV6dPDjNc$scu6EDbt9s</NotificationURI>
<ObjectType>EXPRPT</ObjectType>
<ObjectURI>https://www.concursolutions.com/api/expense/expensereport/v1.1/reportfulldetails/nxxKgLlnROzz$sHcpnRHQ$pALxamClaFfdC</ObjectURI>
</Notification>
</NotificationList>
JSON Example of Successful Response
HTTP/1.1 200 OK
Content-Length: 388
Content-Type: application/json; charset=utf-8
[
{
"Context": null,
"EventDateTime": "2012-11-14T19:45:25",
"EventType": "Report Entered Expense Report Workflow Step - REPORT SUBMITTED",
"NotificationURI": "https://www.concursolutions.com/api/platform/notifications/v1.0/notification/nOB1KNTDSWUcJPMV6dPDjNc$scu6EDbt9s",
"ObjectType": "EXPRPT",
"ObjectURI": "https://www.concursolutions.com/api/expense/expensereport/v1.1/reportfulldetails/nxxKgLlnROzz$sHcpnRHQ$pALxamClaFfdC"
}
]
Launch an External URL Request
SAP Concur will send a request with the information in an encoded query string when the user clicks the button.
Launch An External URL - Request
URI
The Launch External URL callout launches the URI for the application connector, which can be in a custom location for each client. The standard location is:
https://{servername}/concur/form/v1.0/get
The URI is configured on the Register Application Connector page in Web Services under Administration.
The full URI for the request includes the following query string values:
https://{servername}/concur/form/v1.0/get?xcompanydomain={URL-encoded company domain}
&xuserid={URL-encoded login ID of interactive user}
&itemurl={URL-encoded url to item}
&nonce={URL-encoded timestamp}
&signature={URL-encoded signature hash}
Request Schema
| Value | Description |
|---|---|
| xcompanydomain | The company domain. |
| xuserid | The SAP Concur user ID of the logged-in user. This may be an expense delegate instead of the report owner. To get the report owner ID, use the itemurl to get the details of the expense entry, then use those details to get the associated report details, including the report owner ID. |
| itemurl | The URL-encoded URI to access the item the field appears on. An example would be the expense entry URI used by the Expense Report web service. |
| nonce | The URL-encoded GUID used to generate the signature. |
| signature | The URL-encoded signature hash. |
Launch An External URL - Authentication
To authenticate the request, the developer of the page in the application connector will need to generate an auth signature and compare it with the one passed in the query string.
When the request is received by the connector:
- Obtain the username and password for the application connector. How you do this will be specific to your implementation.
- Parse and URL decode the following from the query string:
- xcompanydomain
- xuserid (used for subsequent web service call)
- itemurl
- nonce
- signature (used to authenticate and verify the request)
- Base64-decode the provided signature.
- Calculate your own base signature string by appending the values as such:
{xcompanydomain} + {xuserid} + {itemurl} + {connector username} + {connector password} + {nonce} - Use HMacSHA1 to generate a signature hash using the base signature string. To generate the key, concatenate the lower-case value for {connector username} and the exact {connector password}. For example, if the connector user name is JohnDoe, and the password is password, the key would be johndoepassword.
- Compare the generated signature hash with the signature hash provided in the request query string. If the signature hashes match then you know the credentials are valid and the request has not been tampered with.
NOTES:
- You can store the nonce to help prevent replay attacks if necessary.
- The order of the query parameters is not important, but the values in the base signature string must be combined in the correct order to generate the signature hash correctly.
Launch An External URL - XML Example Request
GET https://{URL to your custom connector and endpoint}
?xcompanydomain={URL-encoded company domain}
&xuserid={URL-encoded login ID of interactive user}
&itemurl={URL-encoded url to item}
&nonce={URL-encoded timestamp}
&signature={URL-encoded signature hash}
Launch An External URL - Response
Content Body
The application connector does not directly respond to the Launch External URL request. The application connector completes any updates to SAP Concur using the Inbound Web Services. The Launch External URL functionality monitors the external window, and when the window is closed, it redraws the form the user launched from to display any updated values.
Launch External URL Callout
The Launch External URL callout gives clients and developers a platform to extend the functionality of SAP Concur providing a means to deliver custom user interactions, or access functionality found in an external system. The client can arrange to add an Expense Entry form field that is configured to use the Launch External URL callout to a Concur Expense Entry form. Concur Expense will display this field with an attached button that launches a separate window when clicked. The window is controlled by an application connector, created by a third-party developer, the client, or SAP Concur. The application connector is a web server that presents information in the window.
The application connector can access SAP Concur data through the web services, or can access data in an external system. Once the user has completed their actions in the window (such as performing a search or completing a wizard), he/she clicks a button such as "Done" that indicates the user has concluded their work in the window. The application connector then closes the window.
The application connector can use web services to send information to SAP Concur to update field values on the expense entry form or other form types. The application connector may send the updates before or after the user closes the window. When the user returns to SAP Concur, the page refreshes and he/she sees the updated values.
This callout differs from the standard SAP Concur web services in the following ways:
- It uses an outbound callout where Expense calls a public facing URL provided by the application connector, which is a web server hosted by the third-party developer or client. The connector domain and IP address must be whitelisted by SAP Concur during the configuration process.
- The application connector can also use the web services to retrieve or send SAP Concur data.
- The developer or client can configure and maintain the public web service interface (the application connector), or the connector can be maintained by SAP Concur. This guide specifies the request and response format required by SAP Concur.
- The client Expense administrator must configure a new form field and add the field to the desired form before this service can be used.
Contents
- Process Flow
- Products and Editions
- Product Restrictions
- Callout Details
- Launch URL Process Overview
- Security
- Authentication
- Functions
- Concur Expense Configuration
- Responses and Errors
Launch External URL Callout - Process Flow

Launch External URL Callout - Products and Editions
- Concur Expense Professional Edition
Launch External URL Callout - Product Restrictions
This callout is not supported in the SAP Concur mobile application.
SAP Concur products are highly configurable, and not all clients will have access to all features.
Only the Employee role can interact with the Launch External URL configured field. Other roles such as the Approver and Processor are not able to trigger the pop-up window.
Partner developers must determine which configurations are required for their solution prior to the review process.
Existing clients can work with SAP Concur Integration Services to create custom applications that work with their configuration.
Launch External URL Callout - Callout Details
Information on how to download, install, and configure the application connector is included in Callouts and Application Connectors.
Launch External URL Callout - Process Overview
The configuration process has the following steps:
- Third-party developer, client or SAP Concur downloads, installs, configures, and customizes the application connector. The application connector may make requests to the inbound web services.
- SAP Concur registers the application connector. SAP Concur must add the IP address and domain of the application connector to an include list. Be ready to supply the test and production domain information.
- Expense Admin creates a new form field with the Launch External URL control type and adds the field to the expense entry form(s).
Once the configuration is complete, the callout uses the following process:
- The user clicks the button next to the read-only form field.
- Expense launches a new window and sends the Expense Entry Details URI, Company Domain, and X-User ID in an encoded query string to the application connector.
- The application connector parses the query string to extract the sent data.
- The application connector uses a SAP Concur web service to gather information. This may be expense entry information, user information, or other information.
- The application connector presents a web page in the new window for the user to interact with. This can be a page from a commercial application, or a custom web application.
- The user completes the external system process. This could be a search, a wizard, or another process.
- The application connector sends any field update information to SAP Concur using the SAP Concur web services.
- The user or the application connector closes the window and returns to SAP Concur.
- SAP Concur reloads the page the user came from in order to display any updated field values.
Launch External URL Callout - Security
SAP Concur will make calls to the application connector's endpoint using SSL. During configuration, SAP Concur will connect to the application connector to validate that its hostname and access credentials are valid.
In the code SAP Concur provides for a sample application connector, credentials are stored in a web configuration file that varies by platform, such as web.xml or web.config. However, if you are hosting the connector, you can customize where and how the credentials are stored by customizing HTTPBasicAuth.java or Authentication.cs.
Expense will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. You will need to install the signed certificate before SAP Concur can access the connector.
Launch External URL Callout - Authentication
SAP Concur sends requests to the application connector using anonymous authorization (no username and password are provided) over HTTPS.
The application connector can validate the authenticity of the query by generating a signature hash from the provided variables and comparing it with the passed in values, including the signature hash that SAP Concur supplies. Two of the required variables for the signature hash are username and password, which are entered in SAP Concur on the Register Application Connector page in Web Services under Administration. The application connector must use the same username and password pair to generate it's validation signature hash.
Launch External URL Callout - Functions
Launch External URL Callout - Concur Expense Configuration
An Expense text form field must be configured as the Launch URL control type and the form field must be added to the desired form before this callout can be used. The Launch URL control type will not appear in the list until a partner application using the Launch External URL API has been registered and enabled for the company. The administrator must select either a single-line or a multi-line control type, depending on the data that will be placed in the field.
Notes:
- The Launch External URL currently only works with Professional Edition.
- It is also only available to be configured at the Expense Entry-level fields.
- This Callout cannot be used with Standard Edition clients or from a Travel or Invoice field.
Launch External URL Callout - Responses and Errors
Refer to the HTTP Codes page for details of the common responses and errors.
Post an event notification request
Post an event notification - Request
Supported Accept Types
- application/xml
URI
The Event Notification callout sends the notification to a URI for the application connector, which can be in a custom location for each client. The standard location is:
https://{servername}/concur/v1.0/notify
The URI is configured on the Register Application Connector page in** Web Services** under Administration.
Request Headers - Required
Authorization header with Basic authorization for endpoint. Refer to Authentication for more information.
Request Headers - Optional
None
Post an event notification request - Request Schema
The request will include a Notification parent element, with the following child elements:
| Element | Description |
|---|---|
| EventType | The event that triggered the callout. Format: Report Entered Expense Report Workflow Step - |
| ObjectType | The type of object that triggered the notification. Currently supports Expense Report and Travel Request. Format: EXPRPT, TRAVELREQ |
| ObjectURI | The URI for the object. The developer can use the appropriate GET endpoint for the Object Type. |
| EventDateTime | When the event happened. Format: YYYY-MM-DD |
| Context | Message that the callout can use to provide the developer some context for the callout. |
Post an event notification request - XML Example Request
POST /concur/v1.0/notify HTTPS/1.1
Host: www.example.com
Authorization: Basic Y29uY3VyOmNvbmN1cg==
...
<?xml version="1.0" encoding="UTF-8" ?>
<Notification>
<EventType>Report Entered Expense Report Workflow Step - SUBMIT</EventType>
<ObjectType>EXPRPT</ObjectType>
<ObjectURI>https://www.concursolutions.com/api/expense/expensereport/v1.1/reportfulldetails/3%Rek29$wsIY12Di3LS9$gjei%KL23</ObjectURI>
<EventDateTime>2012-05-01</EventDateTime>
<Context/>
</Notification>
Post an event notification request - Response
Supported Content Types
- application/txt
Content Body
The application connector responds with an HTTP 200 code when it successfully receives the notification.
Post an event notification request - Example of Successful Response
HTTPS 200 Success
Post an attendee search request
Post an attendee search request - Request
URI
The Fetch Attendee version 2.0 callout sends the attendee information to a URI for the application connector, which can be in a custom location for each client. The default is:
https://{servername}/concur/attendee/v2.0/fetch
For backward compatibility, Fetch Attendee version 1.0 is used instead of version 2.0 when the URI uses v1.0 instead of v2.0. The URI is configured on the Application Connector Registration page under Web Services>Administration>Manage Applications.
The application connector responds to the Fetch Attendee request by returning all attendees that match the search criteria. The result is limited to the maximum number of records specified in the request. If more than the maximum number of records are sent, SAP Concur Expense displays a message in the Attendee Search window asking the user to refine their search. The authorization functionality in version 2.0 is the same as version 1.0
Headers
Authorization Header
Required. Authorization header with Basic authorization for endpoint. Refer to Authentication for more information.
Post an attendee search request - Request Schema
The request body contains an AttendeeSearchRequest parent element with an Attendee child element. The Attendee elements contain the values entered on the search form.
Attendee Elements
| Element | Description |
|---|---|
| AttendeeTypeCode | Code for the attendee type assigned to this attendee. Maximum length is 8 characters. |
| Company | Attendee's company. Also used for Institution Name for Healthcare Provider attendees. Maximum length is 150 characters. Required in the response. |
| Custom1 through Custom20 | Custom fields which vary for a given configuration. Maximum length is 100 characters. Required in the response. For clients who purchased the HCP Connector, Custom7, Custom8, and Custom9 are mapped to the HCP Attendee Form as follows: Custom7: License number Custom8: State of license Custom9: Healthcare specialty description |
| Custom21 through Custom25 | Custom fields which vary for a given configuration. Maximum length is 100 characters. Required in the response. For clients who purchased the HCP Connector, Custom15, Custom21, Custom22, and Custom23 are mapped to the HCP Attendee Form as follows: Custom15: Healthcare practice address Custom21: Attendee taxonomy Custom22: Attendee tax ID Custom23: Covered recipient ID |
| ExternalID | Attendee's unique identifier outside of SAP Concur. Maximum length is 48 characters. |
| FirstName | Attendee's first name. Maximum length is 50 characters. |
| LastName | Attendee's last name. Maximum length is 132 characters. |
| MaximumNumberRecords | Maximum number of records that will be returned to the user for the given search criteria. |
| MiddleInitial | Attendee's middle initial. Maximum length is 1 character. |
| OwnerLoginID | SAP Concur Login ID for the report owner (not the logged in user). The developer can use the User Resource: GET endpoint to obtain user profile details that identify the user and use this information to search for attendees in the system of record for that user. |
| Suffix | Attendee's name suffix. Maximum length is 32 characters. |
| Title | Attendee's title. Maximum length is 32 characters. |
Post an attendee search request - XML Example Request
POST /concur/attendee/v1.0/fetch HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml; charset=utf-8
Content-Length: {length of content body}
<AttendeeSearchRequest>
<Attendee>
<AttendeeTypeCode>BUSGUEST</AttendeeTypeCode>
<FirstName>Chris</FirstName>
<MiddleInitial />
<LastName>Miller</LastName>
<Suffix />
<Title>CFO</Title>
<Company>Len Dev</Company>
<ExternalID />
<OwnerLoginID>cm@example.com</OwnerLoginID>
<MaximumNumberRecords>500</MaximumNumberRecords>
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8>North America</Custom8>
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<Custom21 />
<Custom22 />
<Custom23 />
<Custom24 />
<Custom25 />
</Attendee>
</AttendeeSearchRequest>
Post an attendee search request - Response
Supported Content Types
application/xml
Response Schema
The response will include an AttendeeSearchResponse parent element, with an Attendee child element for each search result.
If no attendees match the search criteria, the response returns an empty AttendeeSearchResponse.
Attendee Elements
The Attendee child element must contain all of the elements described below. The FirstName, LastName, and ExternalID elements must have values. All other elements must be returned in the response, however they can be empty if no data is available.
| Element | Description |
|---|---|
| AttendeeTypeCode | The attendee type code for the attendee type assigned to this attendee. Maximum length: 8 |
| Company | The attendee's company. Required in the response. Also used for Institution Name for Healthcare Provider attendees. Maximum length: 150 |
| Custom1 through Custom25 | Varies depending on configuration. Required in the response. Maximum length of Custom1 through Custom20: 100 characters. Maximum length of Custom21 through Custom25: 48 characters. For information about Custom fields that are used by healthcare providers, see the Custom fields for healthcare provider attendees table below. |
| ExternalID | The attendee's unique identifier outside of SAP Concur. Maximum length: 32 |
| FirstName | The attendee's first name. Maximum length: 50 |
| LastName | The attendee's last name. Maximum length: 132 |
| MiddleInitial | The middle initial of the attendee. Maximum length: 1. |
| Suffix | The suffix of the attendee. Maximum length: 32. |
| Title | The attendee's title. Maximum length: 32 |
Custom Fields for Healthcare Provider Attendees
| Field | Description |
|---|---|
| Custom7 | License Number |
| Custom8 | State of License |
| Custom9 | Specialty Description |
| Custom13 | Recipient Type/Professional Designation |
| Custom14 | NPI Number |
| Custom15 | Primary Practice Address Line 1 |
| Custom16 | Primary Practice Address Line 2 |
| Custom17 | Primary Practice Address Line 3 |
| Custom18 | Primary Practice City |
| Custom19 | Primary Practice State |
| Custom20 | Primary Practice Zip Code |
| Custom21 | Taxonomy. Max 48 characters. |
| Custom22 | Tax ID. Max 48 characters. |
| Custom23 | Covered Recipient ID. Max 48 characters. |
NOTES:
- When implementing the search logic, the search criteria should use logical AND between the fields, not logical OR. For example, if in the search dialog the user specifies Doe in the last name field and Acme in the company field, the connector must return only records where the Acme company has contacts with the last name of Doe. It must not return records for contacts with the last name Doe who belong to another company such as Apex.
- If the application connector does not respond or returns an error, the user is notified in a popup window within Expense. SAP Concur will not resend the request unless the user manually initiates the search again.
Post Fetch Attendee - XML Example of Successful Response
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<AttendeeSearchResponse>
<Attendee>
<ExternalID>1234567890</ExternalID>
<FirstName>Chris</FirstName>
<MiddleInitial>T</MiddleInitial>
<LastName>Miller</LastName>
<Suffix/>
<Company>Len Dev</Company>
<AttendeeTypeCode>BUSGUEST</AttendeeTypeCode>
<Title>CFO</Title>
<Custom1/>
<Custom2/>
<Custom3/>
<Custom4/>
<Custom5/>
<Custom6/>
<Custom7>RD</Custom7>
<Custom8>North America</Custom8>
<Custom9>Internal Medicine</Custom9>
<Custom10/>
<Custom11/>
<Custom12/>
<Custom13/>
<Custom14/>
<Custom15>100 Main Street, Bellevue, WA 98040</Custom15>
<Custom16/>
<Custom17/>
<Custom18/>
<Custom19/>
<Custom20/>
<Custom21>Tax ID 1234</Custom21>
<Custom22/>
<Custom23>Patient ID 576</Custom23>
<Custom24/>
<Custom25/>
</Attendee>
</AttendeeSearchResponse>
The following example shows the expected response when no attendees match the search criteria.
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<?xml version="1.0" encoding="utf-8"?>
<AttendeeSearchResponse/>
Post a list search request
Post A List Search - Request
Supported Accept Types
application/xml
URI
The Fetch List callout sends the attendee information to a URI for the application connector, which can be in a custom location for each client. The standard location is:
https://{servername}/concur/list/v1.2/fetch
The URI is configured on the Register Application Connector page in Web Services under Administration.
Request Headers - Required
Authorization header with Basic authorization for endpoint. Refer to Authentication for more information.
Request Headers - Optional
None
Post A List Search - Request Schema
The request will contain a fetch-list-request parent element, containing the following child elements.
| Element | Description |
|---|---|
long-code |
The long code is a concatenated string containing the parent list item keys separated by a hyphen (-). |
short-code |
The short code is the key of the parent list item. |
query |
It is possible that the asterisk wildcard will be passed from Expense to the application connector.
|
search-by |
Indicates which list item attribute should be searched. Supported values: TEXT, CODE.NOTE: The application connector must support both attributes in order to properly handle wildcard searches. |
lang-code |
The two character code for the language of the user. |
num-to-return |
Expense will specify the number of items to return. The application connector must use this value to ensure that it does not return more results than requested. There is a system limit of 1000 items. |
protected-list-key |
Internal connector information, not used by customers. |
list-name |
Internal connector information, not used by customers. |
connector-version |
Internal connector information, not used by customers. |
config-options |
Internal connector information, not used by customers. |
code-by-level |
Indicates the code at each level in the case of a multi-level list. |
XML Example Request for Single Level List
The example uses the Fetch List web service to search a single level list for all projects beginning with Alph, and is configured to connect to an application connector located at www.example.com.
POST /concur/list/v1.2/fetch HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml; charset=utf-8
Content-Length: {length of content body}
<?xml version="1.0" ?>
<fetch-list-request>
<long-code></long-code>
<short-code></short-code>
<query>Alph*</query>
<search-by>TEXT</search-by>
<lang-code>EN</lang-code>
<num-to-return>500</num-to-return>
<protected-list-key />
<list-name />
<connector-version />
<config-options />
</fetch-list-request>
XML Example Request for Multi-Level List
The example uses the Fetch List web service to search a connected list for all cities under US-W-CA (United States, Western Region, California) beginning with San, and is configured to connect to an application connector located at www.example.com.
POST /concur/list/v1.2/fetch HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml; charset=utf-8
Content-Length: {length of content body}
<?xml version="1.0" ?>
<fetch-list-request>
<long-code>US-W-CA</long-code>
<short-code>CA</short-code>
<query>San*</query>
<search-by>TEXT</search-by>
<lang-code>EN</lang-code>
<num-to-return>500</num-to-return>
<protected-list-key />
<list-name />
<connector-version />
<config-options />
<code-by-level>
<level1>US</level1>
<level2>W</level2>
<level3>CA</level3>
</code-by-level>
</fetch-list-request>
Post a list search - Response
Supported Content Types
application/xml
Post a list search - Response Schema
The application connector responds to the Fetch list web service request by returning all list items that match the search criteria.
The response will include a fetch-list-response parent element, with an item child element for each search result. If there are no search results, the fetch-list-response element is empty. The item child element contains the following child elements:
| Element | Description |
|---|---|
code |
Required The long code for the list item, consisting of the long code from the request combined with the short code from the response, separated by a hyphen (-). |
short-code |
Required The short code for the list item. |
text |
Required The list item text. |
match-value |
Required The value that matched the search term. |
Post a list search request - XML Example of Response with Results
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<fetch-list-response>
<item>
<code>US-W-CA-SF</code>
<short-code>SF</short-code>
<text>San Francisco</text>
<match-value>San Francisco</match-value>
</item>
<item>
<code>US-W-CA-SD</code>
<short-code>SD</short-code>
<text>San Diego</text>
<match-value>San Diego</match-value>
</item>
<item>
<code>US-W-CA-SJ</code>
<short-code>SJ</short-code>
<text>San Jose</text>
<match-value>San Jose</match-value>
</item>
</fetch-list-response>
Post a list search - XML Example of Response with No Results
HTTPS/1.1 200 OK
Content-Type: application/xml
<fetch-list-response>
</fetch-list-response>
Travel Request Validation
Requests in SAP Concur can be validated in an external system by using a combination of SAP Concur's callouts and web services.
This guide provides a step by step overview of how to set up and use the external validation functionality for Requests. This guide does not provide instruction on the process of programming the application connector, but provides an overview of the required functionality.
- Create an Application Connector
- Configure Event Notification and Request in SAP Concur
- Gather the Request Details
- Validate the Request Information
- Update the Request Workflow
Step 1 - Create an Application Connector
The application connector is a custom web application that is installed on your company's web server. This application needs to be accessible from outside your company's network, so that SAP Concur can send information to it, and it needs to have access to the system that you are using for validation. The application connector must be configured to accept the event notification requests from SAP Concur. In later steps, you will expand the functionality of the application connector to perform additional tasks. The required connector configuration for this step is:
- You must have a current security certificate installed on the server that hosts the application connector.
- You must expose an endpoint on your web server that SAP Concur can connect to. This endpoint can have any name or location. The default endpoint is: /concur/v1.0/notify
- You must be able to accept an HTTP POST from SAP Concur with the event notification data. Refer to the Event Notification information for details of the information format. You just need to store the data that SAP Concur sends for this step.
- You must have a username and password configured for the host web server, which SAP Concur will use when sending the HTTP POST request. This username and password is sent using HTTP Basic Auth.
Once you have the basic application connector functionality set up, you're ready to move to the next step.
Step 2 - Configure Event Notification and Request in SAP Concur
In this step, you will enable the Event Notification functionality in your SAP Concur company in order to receive information about submitted Requests. Then, you will enable the Request API in order to request Request details from SAP Concur.
Before you begin:
- You must have a user login with administrative privileges in SAP Concur.
- You must know which Request workflows require the Event Notification functionality.
Procedure: Create the Event Notification Application Connector
- Log in to SAP Concur as an administrative user.
- Select Administration > Web Services.
- Click Manage Application Connectors.
- Click New.
- Fill out the fields:
| Field | Description |
|---|---|
| Name | Enter the name that should appear in the list of connectors. |
| Description | Enter the description of the function of the connector, such as what back-end system it connects to. |
| Host Name | Enter the hostname for the connector. Example: https://{servername} |
| User Name | Enter the user name required to authenticate with the host. This must be the same as the user name specified in the configuration file for the application connector, using HTTP Basic Auth. |
| Password | Enter the password required to authenticate with the host. This must be the same as the password specified in the configuration file for the application connector, using HTTP Basic Auth. |
- In the Services section, select External Report Validation.
- Click Configure. The Configure Service window appears.
- Enter the endpoint that the SAP Concur will connect to on your server. Example: /concur/v1.0/notify
- Select the Enabled check box.
- In the Workflows section, select the Submit check box for each Request workflow that requires notifications.
- Click OK.
- Click Test Connection. SAP Concur will attempt to access the configured endpoint with the provided user credentials.
- Click Save. The application connector is now registered with SAP Concur and enabled.
Procedure: Create the Request Partner Application
- On the Web Services page, click Register Partner Application. The Application Registration page appears.
- Click New. The New Partner Application page appears.
- Complete all of the required fields:
| Field | Description |
|---|---|
| Name | Enter the name that should appear in the list of applications. |
| Description | Enter the description of the function of the application. |
| Visibility | This field is only editable by SAP Concur Internal users. |
| Active | Select Active. |
| APIs Used | Select the Request API. |
- The Application Authorization section displays your company domain and automatically creates a Key and Secret to use with this application.
NOTE: The key and secret allow access to any company that enables this application. You MUST keep this information secret (as specified in the SAP Concur Legal Agreement) to maintain security. - Record the key and secret to use later.
- Click OK. The application will automatically be enabled for your company.
You should now begin receiving notifications from SAP Concur when your users submit Requests. In the next step, you'll use the notification data that SAP Concur sends to get the Request information.
Step 3 - Gather the Request Details
In this step, you will expand the application connector functionality to use the data sent by SAP Concur in the event notification to get details about the Request. You'll use the Request details to validate the Request in a later step. The application connector must be updated to perform the following steps, using the SAP Concur web services:
Get OAuth Access Token
All requests to SAP Concur web services must be authenticated using OAuth 2.0.
After receiving an event notification, the application connector should send an HTTP GET request to the Get Access Token using Native Flow function. This function requires the login credentials of an administrative SAP Concur user and the Consumer Key that was generated when you created the partner application in the previous step. Refer to the Get Access Token using Native Flow documentation for the format of the request. SAP Concur will respond to the request with the access token required for the next web service request.
Get Request Details
After you receive the OAuth access token, you are ready to request the Request data. The event notification information that SAP Concur sends includes an element named ObjectURI. The connector can send a GET request to the URI specified in this element, supplying the OAuth access token in the request header in the following format:
GET api/travelrequest/v1.0/requests/nxxKgLlnROz3zHJBCRksaas23dsfs HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...
Step 4 - Validate the Request Information
In this step, the connector will perform the required validation on the Request information. This step will vary by client. The application connector must be able to access the system(s) used in the validation.
The Request data is validated by the application connector. The validation can produce one of the following results:
- The Request passed validation and can be approved.
- The Request did not pass validation and must be returned to the employee with an informational message explaining the problem.
In the next step, the application connector will update the Request with the validation results.
Step 5 - Update the Request Workflow
Once the Request has been validated, the application connector is ready to update its workflow. If the Request passed validation, it should be approved, and will then travel forward in its workflow. If the Request did not pass validation, it should be sent back to the employee, which moves it to the beginning of the workflow.
The full Request details include an element named WorkflowStepURL. The application connector posts the workflow action (Approve or Send Back to Employee) to this url, using the same OAuth access token in the header.
SAP Concur responds with a success or failure status, and provides additional information for failures.
The application connector has now completed the process of validating a Request, from the initial notification that a Request was submitted, to the request updating the Request workflow in SAP Concur with the validation results.
Common
Connection Requests v3.2
The Connection Requests resource is used to integrate TripLink partner applications with Concur. It can be used to create, update, and manage connections between a user's Concur account and a select travel loyalty program. With Connection Requests a TripLink partner application can retrieve new connection requests in order to match users who want to connect to the supplier with the user's account in the supplier system. After the request is retrieved, the supplier is expected to provide a status if the connection was successful or failed. When retrieving new connections, the results can be filtered by status, page offset, and a limit for the number of records to return.
In version 3.2, connection requests can also associate users to either loyalty programs, Concur verified e-mail addresses, or both of these factors. Concur verified emails are email addresses where a user has taken additional steps to confirm an email belongs to them by entering a verification code within the Concur UI after receiving this in their email. Verified emails have uniqueness across all user accounts in the Concur system.
The use of loyalty numbers and/or verified emails to identify users is based on the business agreement between Concur and the TripLink supplier and will be discussed during the TripLink integration kick-off process. Email or loyalty number will not be returned in the connection request if the supplier is not using these factors in their process to match a user in their system to a Concur user.
Concur's recommendation for suppliers is to match users requesting to connect utilizing last name and loyalty number only. Or in the case of suppliers without loyalty numbers to use verified email and the last name of the user only. The first name and middle name fields have proved to generate a high degree of failures when utilized due to issues like nicknames within the supplier systems.
- Retrieve all connection requests that match the TripLink supplier ID
- Retrieve a connection request by ID
- Create a connection request on behalf of a specific user
- Update a connection request
- Schema 3.2
- Schema 3.0 (deprecated)
Connection Requests v3.0 is deprecated.
Connection Requests v3.1 is deprecated.
Retrieve all connection requests that match the TripLink supplier ID
GET /api/v3.2/common/connectionrequests/
GET /api/v3.0/common/connectionrequests/ (deprecated)
GET /api/v3.1/common/connectionrequests/ (deprecated)
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
offset |
query |
string |
The starting point of the next set of results, after the limit specified in the limit field has been reached. The default is the beginning of the page. |
limit |
query |
Int32 |
The number of records to return. The default is 5 and the maximum is 10. |
status |
query |
string |
The status code representing the state of the connection request. The possible values are Pending, Processing, Connected, Failed, and Retry. |
Retrieve a connection request by ID
GET /api/v3.2/common/connectionrequests/{id}
GET /api/v3.0/common/connectionrequests/{id} (deprecated) GET /api/v3.1/common/connectionrequests/{id} (deprecated)
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
path |
string |
Required The connection request ID. |
Create a connection request on behalf of a specific user
POST /api/v3.2/common/connectionrequests/
POST /api/v3.0/common/connectionrequests/ (deprecated) POST /api/v3.1/common/connectionrequests/ (deprecated)
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
user |
query |
string |
Required The login ID of the user for whom to create the connection request. The user must have the Web Services Admin role to use this parameter. |
Update a connection request
PUT /api/v3.2/common/connectionrequests/{id}
PUT /api/v3.0/common/connectionrequests/{id} (deprecated) PUT /api/v3.1/common/connectionrequests/{id} (deprecated)
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
path |
string |
Required The connection request ID. |
content |
body |
- | Required The connection request object to update. |
Schema 3.2
Connection Requests
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Connection Request | The result collection. |
NextPage |
string |
The URI of the next page of results, if any. |
Connection Request
| Name | Type | Format | Description |
|---|---|---|---|
firstName |
string |
- | The user's first name. |
ID |
string |
- | The unique identifier of the resource. |
lastModified |
string |
- | The date and time when the connection request was last modified. Format: UTC |
lastName |
string |
- | The user's last name. |
loyaltyNumber |
string |
- | The user's travel loyalty number. |
middleName |
string |
- | The user's middle name. |
requestToken |
string |
- | The request token. |
status |
string |
- | The status code representing the state of the connection request. |
URI |
string |
- | The URI to the resource. |
userId |
string |
- | The unique identifier of the user. |
emailAddresses |
UserEmailAddresses |
User Email Addresses | Email addresses associated with the user. |
User Email Addresses
| Name | Type | Format | Description |
|---|---|---|---|
email1 |
string |
- | The user's verified email address. |
email2 |
string |
- | The user's verified email address. |
email3 |
string |
- | The user's verified email address. |
email4 |
string |
- | The user's verified email address. |
email5 |
string |
- | The user's verified email address. |
Schema 3.0 (Deprecated)
Connection Requests
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Connection Request | The result collection. |
NextPage |
string |
The URI of the next page of results, if any. |
Connection Request
| Name | Type | Format | Description |
|---|---|---|---|
FirstName |
string |
- | The user's first name. |
ID |
string |
- | The unique identifier of the resource. |
LastModified |
string |
- | The date and time when the connection request was last modified. Format: UTC |
LastName |
string |
- | The user's last name. |
LoyaltyNumber |
string |
- | The user's travel loyalty number. |
MiddleName |
string |
- | The user's middle name. |
RequestToken |
string |
- | The request token. |
Status |
string |
- | The status code representing the state of the connection request. |
URI |
string |
- | The URI to the resource. |
Schema 3.1 (Deprecated)
Connection Requests
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Connection Request | The result collection. |
NextPage |
string |
The URI of the next page of results, if any. |
Connection Request
| Name | Type | Format | Description |
|---|---|---|---|
FirstName |
string |
- | The user's first name. |
ID |
string |
- | The unique identifier of the resource. |
LastModified |
string |
- | The date and time when the connection request was last modified. Format: UTC |
LastName |
string |
- | The user's last name. |
LoyaltyNumber |
string |
- | The user's travel loyalty number. |
MiddleName |
string |
- | The user's middle name. |
RequestToken |
string |
- | The request token. |
Status |
string |
- | The status code representing the state of the connection request. |
URI |
string |
- | The URI to the resource. |
EmailAddresses |
UserEmailAddresses |
User Email Addresses | Email addresses associated with the user. |
User Email Addresses
| Name | Type | Format | Description |
|---|---|---|---|
Email1 |
string |
- | The user's verified email address. |
Email2 |
string |
- | The user's verified email address. |
Email3 |
string |
- | The user's verified email address. |
Email4 |
string |
- | The user's verified email address. |
Email5 |
string |
- | The user's verified email address. |
Extracts v1
- Get an array of extract definitions
- Get a single extract definition
- Get an extract file or files
- Get an array of extract jobs
- Get a single extract job
- Get a single extract job status
- Post an extract job initiation request
- Schema
Capabilities
The Extract web service allows for the development of a customized process that can be used to request and extract available data objects such as “Approved” Expense Reports, Invoices, and Payment Requests.
Through a series of web service calls an Application Connector can GET the Extract Definition List, then use that list to perform a POST the Extract Job of their choosing. This POST will initiate the extract process. While the job runs another process can periodically GET the Extract Job Status and once “Complete” the Connector can then perform a GET to obtain the Extract Job File data.
The series of calls that your connector will make will remain the same for each implementation of the Extract Web Service.
Additionally, it provides:
- Access to extract files using HTTP to move or manage the data as opposed to using a secure FTP site.
- Clients with organizational units around the globe can create and receive extracts at times that work best for their time zones. To accomplish this, you can work with your SAP Concur support resource to create a unique Extract Definition for each organizational unit that requires a separate extract.
- A way to receive extract files throughout the day including, but not limited to, outside the Overnight Processing Period (ONP).
Note: A client may elect to include additional functionality that could result in complex journal entries. For example, they may allow cash advances or utilize a company-paid corporate card program where personal amounts result in an employee owing the employer. These configuration choices require more care when pulling the extract file from SAP Concur. Work with their functional experts on their specific use case, then watch the relevant videos in the SAE Detailed Discussions section at the bottom of the page for detailed information on which fields to include.
Resource URI
https://{InstanceURL}/api/expense/extract/v1.0
https://{InstanceURL}/api/expense/extract/v1.0/{DefinitionID}/job
https://{InstanceURL}/api/expense/extract/v1.0/{DefinitionID}/job/status
https://{InstanceURL}/api/expense/extract/v1.0/{DefinitionID}/job/{JobID}/file
Version
1.0
Base URI
/api/expense/extract/v1.0/
Authorization
The Authorization header with OAuth token for a valid SAP Concur user must be included with all API calls. The OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. These roles allow the user to manage data for the entire company.
Get an Array of Extract Definitions
Request
Headers
Parameters
None
Payload
| Name | Type | Format | Description |
|---|---|---|---|
name |
type |
JSON | Required Description. |
Response
Status Codes
Headers
- RFC 7231 Content-Type
application/xml
Payload
Example
Request
GET https://www.concursolutions.com/api/expense/extract/v1.0/
Authorization: OAuth {token}
Response
HTTP/1.1 200 OK
Content-Type: application/xml
<definitions xmlns="http://www.concursolutions.com/api/expense/extract/2010/02">
<definition>
<id>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd</id>
<job-link>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job</job-link>
<name>Standard Accounting Extract</name>
</definition>
<definition>
<id>https://www.concursolutions.com/api/expense/extract/v1.0/Umj$swS19lpd7Sk$phUYl67wE1ss4Q$shu</id>
<job-link>https://www.concursolutions.com/api/expense/extract/v1.0/Umj$swS19lpd7Sk$phUYl67wE1ss4Q$shu</job-link>
<name>European Extract</name>
</definition>
<definition>
<id>https://www.concursolutions.com/api/expense/extract/v1.0/8LjhN23Hs33$piUUfy4ytTqa$sqqacYeP1</id>
<job-link>https://www.concursolutions.com/api/expense/extract/v1.0/8LjhN23Hs33$piUUfy4ytTqa$sqqacYeP1</job-link>
<name>Asian Extract</name>
</definition>
</definitions>
Get a single extract definition
Retrieves the details of the specified extract definition.
Request
Headers
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
DefinitionID |
string |
- | Required The identifier for the desired extract definition. |
URI Template
https://www.concursolutions.com/api/expense/extract/v1.0/{DefinitionID}
Payload
| Name | Type | Format | Description |
|---|---|---|---|
name |
type |
JSON | Required Description. |
Response
Status Codes
Headers
- RFC 7231 Content-Type
application/xml
Payload
Example
GET https://www.concursolutions.com/api/expense/extract/v1.0/n59FpBJ8hN3qVWTFIrtxkOT5pef6DmIj3
Authorization: OAuth {token}
Request
HTTP/1.1 200 OK
Content-Type: application/xml
Response
<definition xmlns="http://www.concursolutions.com/api/expense/extract/2010/02" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<id>https://www.concursolutions.com/api/expense/extract/v1.0/n59FpBJ8hN3qVWTFIrtxkOT5$pef6DmIj3</id>
<name>AMEX Remittance - US</name>
<job-link>https://www.concursolutions.com/api/expense/extract/v1.0/n59FpBJ8hN3qVWTFIrtxkOT5$pef6DmIj3/job</job-link>
</definition>
Get an extract file or files
The extracted data for the specified extract job.
The response is the extracted data in text/csv format if there was a single file produced or as application/zip if the extract definition is configured to produce more than one file.
Request
Headers
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
DefinitionID |
string |
- | Required The definition identifier. |
JobID |
string |
- | Required The identifier for the job. |
URI Template
https://www.concursolutions.com/api/expense/extract/v1.0/{DefinitionID}/job/{JobID}/file
Payload
| Name | Type | Format | Description |
|---|---|---|---|
name |
type |
JSON | Required Description. |
Response
Status Codes
Headers
- RFC 7231 Content-Type
text/csvapplication/zip
Payload
| Name | Type | Format | Description |
|---|---|---|---|
name |
type |
format | description |
Example
GET https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uIo87jk3SHudi$sdlYle8$peot$pD21jyd/file
Authorization: OAuth {token}
Request
HTTP/1.1 200 OK
Content-Type: text/csv
100,AAA,BBBB,CCCC,...<rest of file>
Response
HTTP/1.1 200 OK
Content-Type: application/zip
{ zip archive data}
Single file
Multiple files
Get an Array of Extract Jobs
Requests a list of the last 100 extract jobs ran for the specified Extract Definition.
Request
Headers
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
DefinitionID |
string |
- | Required The definition identifier. |
URI Template
https://www.concursolutions.com/api/expense/extract/v1.0/{DefinitionID}/job
Payload
| Name | Type | Format | Description |
|---|---|---|---|
name |
type |
JSON | Required Description. |
Response
Status Codes
Headers
- RFC 7231 Content-Type
application/xml
Payload
Example
GET https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job HTTP/1.1
Authorization: OAuth {token}
Request
HTTP/1.1 200 OK
Content-Type: application/xml
Response
<jobs xmlns="...">
<job>
<id>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uIo87jk3SHudi$sdlYle8$peot$pD21jyd</id>
<status-link>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uIo87jk3SHudi$sdlYle8$peot$pD21jyd/status</status-link>
<start-time>2010-01-13T18:30:02Z</start-time>
<status>Queued</status>
</job>
<job>
<id>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/21UwwqA3jk25Lis77jF$piiD21c89lLwEq</id>
<status-link>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/21UwwqA3jk25Lis77jF$piiD21c89lLwEq/status</status-link>
<start-time>2010-01-13T18:30:02Z</start-time>
<stop-time>2010-01-13T18:30:50Z</stop-time>
<status>Complete</status>
<file-link>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/21UwwqA3jk25Lis77jF$piiD21c89lLwEq/file</file-link>
</job>
<job>
<id>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uI77ndy0Q1szuU73XSh56lshi$p215gHs1</id>
<status-link>https://www.concursolutions.com/api/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uI77ndy0Q1szuU73XSh56lshi$p215gHs1/status</status-link>
<start-time>2010-01-12T18:30:01Z</start-time>
<stop-time>2010-01-12T18:31:01Z</stop-time>
<status>Complete</status>
<file-link>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uI77ndy0Q1szuU73XSh56lshi$p215gHs1/file</file-link>
</job>
</jobs>
Get a Single Extract Job
Retrieves the details of the specified extract definition.
Request
Headers
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
DefinitionID |
string |
- | Required The identifier for the desired extract definition. |
JobID |
string |
- | Required The identifier for the job and the job keyword. |
URI Template
https://www.concursolutions.com/api/expense/extract/v1.0/{DefinitionID}/job/{JobID}
Payload
None
Response
Status Codes
Headers
- RFC 7231 Content-Type
application/xml
Payload
Example
GET https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uIo87jk3SHudi$sdlYle8$peot$pD21jyd
Authorization: OAuth {token}
Request
HTTP/1.1 200 OK
Content-Type: application/xml
Response
<job xmlns="...">
<id>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uIo87jk3SHudi$sdlYle8$peot$pD21jyd></id>
<status-link>https://www.concursolutions.com/api/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uIo87jk3SHudi$sdlYle8$peot$pD21jyd/status</status-link>
<start-time>2010-01-12T18:30:01</start-time>
<stop-time>2010-01-12T18:31:01</stop-time>
<status>Complete</status>
<file-link> https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uIo87jk3SHudi$sdlYle8$peot$pD21jyd/file</file-link>
</job>
Get a Single Extract Job Status
Retrieves the details of the specified extract definition.
Request
Headers
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
DefinitionID |
string |
- | Required The identifier for the desired extract definition. |
JobID |
string |
- | Required The identifier for the job and the job keyword. |
URI Template
https://www.concursolutions.com/api/expense/extract/v1.0/{DefinitionID}/job/{JobID}/status
Payload
None
Response
Status Codes
Headers
- RFC 7231 Content-Type
application/xml
Payload
Example
https://www.concursolutions.com/api/expense/extract/v1.0/nX8O9$pytn6vJEWvLOZxyy3GcNGyj0ZklG/job/nIJp1lR2R0LNT4XcO5fXG$s$sZmVuRTuG$ps/status
{Header}: {Value}
Request
HTTP/1.1 200 OK
Content-Type: application/xml
Response
<job xmlns="http://www.concursolutions.com/api/expense/extract/2010/02" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<id>https://www.concursolutions.com/api/expense/extract/v1.0/nX8O9$pytn6vJEWvLOZxyy3GcNGyj0ZklG/job/nIJp1lR2R0LNT4XcO5fXG$s$sZmVuRTuG$ps</id>
<status-link>https://www.concursolutions.com/api/expense/extract/v1.0/nX8O9$pytn6vJEWvLOZxyy3GcNGyj0ZklG/job/nIJp1lR2R0LNT4XcO5fXG$s$sZmVuRTuG$ps/status</status-link>
<start-time>2011-08-25T14:25:22.58</start-time>
<stop-time>2011-08-25T14:25:23.537</stop-time>
<status>Completed</status>
<file-link>https://www.concursolutions.com/api/expense/extract/v1.0/nX8O9$pytn6vJEWvLOZxyy3GcNGyj0ZklG/job/nIJp1lR2R0LNT4XcO5fXG$s$sZmVuRTuG$ps/file</file-link>
</job>
Post an Extract Job Initiation Request
Initiates a new extract job for the specified extract definition. The job will be scheduled to start as soon as possible. The value will be Queued until the job begins.
Request
Headers
- RFC 7235 Authorization
- RFC 7231 Content-Type
application/xml
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
DefinitionID |
string |
- | Required The identifier for the desired extract definition. |
URI Template
https://www.concursolutions.com/api/expense/extract/v1.0/{DefinitionID}/job
Payload
Response
Status Codes
Headers
- RFC 7231 Content-Type
application/xml - RFC 7231 Location
Payload
Example
POST https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job
Authorization: OAuth {token}
Content-Type: application/xml
Request
HTTP/1.1 201 Created
Location: https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uIo87jk3SHudi$sdlYle8$peot$pD21jyd
Content-Type: application/xml
<definition xmlns="http://www.concursolutions.com/api/expense/extract/2010/02">
<id>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd</id>
</definition>
Response
<job xmlns="...">
<id>https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uIo87jk3SHudi$sdlYle8$peot$pD21jyd</id>
<status-link> https://www.concursolutions.com/api/expense/extract/v1.0/nYoPK$pZmcowMRUqcl5bnDAwwsMydyt$xd/job/uIo87jk3SHudi$sdlYle8$peot$pD21jyd/status</status-link>
<start-time>2010-01-13T18:30:02Z</start-time>
<status>Queued</status>
</job>
Schema
Definitions
| Name | Type | Format | Description |
|---|---|---|---|
definitions |
array |
definition | Required |
Definition
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | The extract definition ID URI with encrypted ID. |
job-link |
string |
- | The extract job URI with encrypted ID. The job-link value is used as the URI when creating the extract job data request. |
name |
string |
- | The extract definition name. |
Jobs
| Name | Type | Format | Description |
|---|---|---|---|
jobs |
array |
job | Required |
Job
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | The unique job identifier with encrypted ID. |
status-link |
string |
- | A URI for retrieving the current job status, with encrypted ID. The status-link value is used as the URI when requesting the job status. |
start-time |
string |
- | The time in UTC (GMT) the job is scheduled to start. |
stop-time |
string |
- | The time in UTC (GMT) the job finished. Not included if the job is still running. |
status |
string |
- | The current status of the job. |
file-link |
string |
- | A URI for retrieving the file or files produced by the job run, with encrypted ID. Not included if the job is still running. The file-link value is used as the URI when retrieving the extract data. |
Enterprise Resource Planning Integration
For the purposes of ERP integration this API is available to Professional Edition. For Standard Edition use Payment Batches v1 API ERP Integration.
- Get an array of extract definitions
- Locate the desired definitions for your client. You may need to obtain additional details as there may be multiple files to obtain depending on client requirements.
- Record the Definition ID to use in subsequent API requests.
- Get an array of extract jobs
- OPTIONAL: the Partner only needs to do this if the Partner is running the job, otherwise skip this step.
- Determine which jobs are interesting and record their
file-link.
- Get an extract file or files
Lists v3
The Lists API allows you to view your configured lists within SAP Concur products, and create new lists. The lists are shared between multiple SAP Concur products. Use the List Items API to manage the items in the lists.
- Products and Editions
- Scope Usage
- Get All Lists
- Create a New List
- Get a Single List by ID
- Update List Deprecated
- Schema
Lists v3 - Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
- Concur Invoice Professional Edition
- Concur Invoice Standard Edition
- Concur Request Professional Edition
- Concur Request Standard Edition
Lists v3 - Scope Usage
| Name | Description | Endpoint |
|---|---|---|
LIST |
Use and update lists configured by your company. | GET, POST |
Lists v3 - Get All Lists
Returns all lists based on the search criteria.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
limit |
integer |
The default is 25 and the maximum is 100. | Optional. The number of records to return. |
offset |
string |
- | Optional. The start of the page offset. The default is from the beginning. |
Request
GET https://www.concursolutions.com/api/v3.0/common/lists HTTP/1.1
Host: www.concursolutions.com
Accept: application/json
const headers = {
'Accept':'application/json'
};
fetch('https://www.concursolutions.com/api/v3.0/common/lists',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
Response
200 Response
{
"Items": {
"ConnectorID": "string",
"DisplayCodeFirst": true,
"ExternalThreshold": 0,
"ID": "string",
"IsVendorList": true,
"Name": "string",
"SearchCriteriaCode": "string",
"URI": "string"
},
"NextPage": "string"
}
Lists v3 - Create a New List
Creates a new list.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
content |
ListPost | - | Required. List object to create. |
Request
POST https://www.concursolutions.com/api/v3.0/common/lists HTTP/1.1
Host: www.concursolutions.com
Content-Type: application/json
Accept: application/json
const inputBody = '{
"ConnectorID": "string",
"DisplayCodeFirst": true,
"ExternalThreshold": 0,
"IsVendorList": true,
"Name": "string",
"SearchCriteriaCode": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json'
};
fetch('https://www.concursolutions.com/api/v3.0/common/lists',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
Response
200 Response
{
"ID": "string",
"URI": "string"
}
Get a Single List by ID
Returns a list by ID.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | Required.The unique identifier for the list. |
Request
GET https://www.concursolutions.com/api/v3.0/common/lists/{id} HTTP/1.1
Host: www.concursolutions.com
Accept: application/json
const headers = {
'Accept':'application/json'
};
fetch('https://www.concursolutions.com/api/v3.0/common/lists/{id}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
Response
200 Response
{
"ConnectorID": "string",
"DisplayCodeFirst": true,
"ExternalThreshold": 0,
"ID": "string",
"IsVendorList": true,
"Name": "string",
"SearchCriteriaCode": "string",
"URI": "string"
}
Lists v3 - Update List
DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016. Updates list specified in the URL. Only the fields provided in the supplied object will be updated, missing fields will not be altered.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | Required. The unique identifier for the list. |
content |
ListPut | - | Required. The list object to update. |
Request
PUT https://www.concursolutions.com/api/v3.0/common/lists/{id} HTTP/1.1
Host: www.concursolutions.com
Content-Type: application/json
Accept: application/json
const inputBody = '{
"DisplayCodeFirst": true,
"Name": "string",
"SearchCriteriaCode": "string"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json'
};
fetch('https://www.concursolutions.com/api/v3.0/common/lists/{id}',
{
method: 'PUT',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
Lists v3 - Schema
CreateResponse
| Name | Type | Format | Description |
|---|---|---|---|
ID |
string |
- | |
URI |
string |
- |
ListGet
| Name | Type | Format | Description |
|---|---|---|---|
ConnectorID |
string |
- | Optional. Defines the encrypted ConnectorID. If not provided then the list isn't associated with a connector. |
DisplayCodeFirst |
Boolean |
- | Required. Defines whether code should appear before text, or vice versa. |
ExternalThreshold |
integer |
- | Optional. Default value is 1. Defines the threshold from where the level starts being external. This value can only be set if a ConnectorID is provided. |
ID |
string |
- | The unique identifier of the resource. |
IsVendorList |
Boolean |
- | Required. Defines whether it is a vendor list. |
Name |
string |
- | Required. Defines a name for the list. This name must be unique. |
SearchCriteriaCode |
string |
- | Required. Defines whether the search criteria should apply to the code or to the text. |
URI |
string |
- | The URI to the resource. |
ListGetCollection
| Name | Type | Format | Description |
|---|---|---|---|
Items |
ListGet | - | |
NextPage |
string |
- | The URI of the next page of results, if any. |
ListPost
| Name | Type | Format | Description |
|---|---|---|---|
ConnectorID |
string |
- | Optional. Defines the encrypted ConnectorID. If not provided then the list isn't associated with a connector. |
DisplayCodeFirst |
Boolean |
- | Required. Defines whether code should appear before text, or vice versa. |
ExternalThreshold |
integer |
- | Optional. Default value is 1. Defines the threshold from where the level starts being external. This value can only be set if a ConnectorID is provided. |
IsVendorList |
Boolean |
- | Required. Defines whether it is a vendor list. |
Name |
string |
- | Required. Defines a name for the list. This name must be unique. |
SearchCriteriaCode |
string |
- | Required. Defines whether the search criteria should apply to the code or to the text. |
ListPut
| Name | Type | Format | Description |
|---|---|---|---|
DisplayCodeFirst |
Boolean |
- | Optional. Defines whether code should appear before text, or vice versa. |
Name |
string |
- | Optional. Defines a name for the list. This name must be unique. |
SearchCriteriaCode |
string |
- | Optional. Defines whether the search criteria should apply to the code or to the text. |
List Item v3
The SAP Concur List Item API provides an automated solution to clients who would like to add, update, or delete list items. Use of the API is subject to some limitations on the volume of List data. You may need to manage the initial load of large volumes of data via a file import due to capacity limitations. This is also true if ongoing maintenance of List values involves a large volume.
- Retrieve all list items based on the search criteria
- Retrieve a list item by ID
- Create a new list item
- Update a list item
- Delete a list item
- Schema
Version
3.0
1.0 documentation is available here
Retrieve All List Items Based on the Search Criteria
GET /api/v3.0/common/listitems
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
limit |
Int32 |
query |
The number of records to return. The default is 25 and the maximum is 100. |
offset |
string |
query |
The start of the page offset. The default is from the beginning. |
listId |
string |
query |
The unique identifier for the list this item is a member. |
name |
string |
query |
The name of the listItem. Text Max length: 64. |
parentId |
string |
query |
The unique identifier of this item's parent. Is empty when there is no parent. |
level1Code |
string |
query |
The item code for the first level of the list. All lists have at least a Level1Code. Text maximum 32 characters |
level2Code |
string |
query |
The item code for the second level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
level3Code |
string |
query |
The item code for the third level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
level4Code |
string |
query |
The item code for the fourth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
level5Code |
string |
query |
The item code for the fifth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
level6Code |
string |
query |
The item code for the sixth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
level7Code |
string |
query |
The item code for the seventh level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
level8Code |
string |
query |
The item code for the eighth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
level9Code |
string |
query |
The item code for the ninth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
level10Code |
string |
query |
The item code for the tenth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
Retrieve a List Item by ID
GET /api/v3.0/common/listitems/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The unique identifier for the listItem. |
listId |
string |
query |
The unique identifier for the list this item is a member. |
Create a New List Item
POST /api/v3.0/common/listitems
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
content |
- | body |
Required List item object to create. |
Update a List Item
PUT /api/v3.0/common/listitems/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The unique identifier for the list item. |
content |
- | body |
Required The list item object to update. |
Delete a List Item
DELETE /api/v3.0/common/listitems/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The unique identifier of the listitem to delete |
listId |
string |
query |
Required The unique identifier of the list associated with a listitem to be deleted |
List Item v3 - Schema
List Items
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
List Item | The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
List Item
| Name | Type | Format | Description |
|---|---|---|---|
ID |
string |
- | The unique identifier of the resource. |
Level10Code |
string |
- | The item code for the tenth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
Level1Code |
string |
- | The item code for the first level of the list. All lists have at least a Level1Code. Text maximum 32 characters |
Level2Code |
string |
- | The item code for the second level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
Level3Code |
string |
- | The item code for the third level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
Level4Code |
string |
- | The item code for the fourth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
Level5Code |
string |
- | The item code for the fifth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
Level6Code |
string |
- | The item code for the sixth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
Level7Code |
string |
- | The item code for the seventh level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
Level8Code |
string |
- | The item code for the eighth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
Level9Code |
string |
- | The item code for the ninth level of the list. Empty when this level doesn't exist in the list. Text maximum 32 characters |
ListID |
string |
- | The unique identifier for the list this item is a member. |
Name |
string |
- | The name of item. Text maximum 64 characters |
ParentID |
string |
- | The unique identifier of this item's parent. Is empty when there is no parent. |
URI |
string |
- | The URI to the resource. |
Locations v3
Gets details of locations that are used by Concur and that are valid at the user's company.
- Retrieve details of locations that are used by Concur and that are valid at the user's company
- Retrieve details of a specified location
- Schema
Location v1.1 has been deprecated and can be found here.
Retrieve details of locations that are used by Concur and that are valid at the user's company
GET /api/v3.0/common/locations
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
offset |
string |
query |
The starting point of the next set of results, after the limit specified in the limit field has been reached. |
limit |
Int32 |
query |
The number of records to return. Default value: 25 |
name |
string |
query |
A common name associated with the location. This name can be a location description such as a neighborhood (SoHo), a landmark (Statue of Liberty), or a city name (New York). |
city |
string |
query |
The city name of the location. |
countrySubdivision |
string |
query |
The ISO 3166-2:2007 country subdivision code for the location. Example: US-WA |
country |
string |
query |
The 2-letter ISO 3166-1 country code for the location. Example: United States is US |
administrativeRegion |
string |
query |
The administrative region of the location. An administrative region is a government unit, such as a county, that contains one or more cities. |
Retrieve details of a specified location
GET /api/v3.0/common/locations/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the location. |
Locations v3 - Schema
Locations
| Name | Type | Format | Description |
|---|---|---|---|
Items |
Array |
Location | The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
Location
| Name | Type | Format | Description |
|---|---|---|---|
AdministrativeRegion |
string |
- | The administrative region of the location. |
Country |
string |
- | The 2-letter ISO 3166-1 country code for the location. |
CountrySubdivision |
string |
- | The ISO 3166-2:2007 country subdivision code for the location. Example: US-WA |
IATACode |
string |
- | The International Air Transport Association (IATA) airport code of the location. |
ID |
string |
- | The unique identifier of the resource. |
IsAirport |
boolean |
- | Indicates whether the location is an airport. Format: true or false |
IsBookingTool |
boolean |
- | Indicates whether the location is used by the booking tool. Format: true or false |
Latitude |
Decimal |
- | The latitude of the geocode for the location. |
Longitude |
Decimal |
- | The longitude of the geocode for the location. |
Name |
string |
- | The location name. Maximum length: 64 characters |
URI |
string |
- | The URI to the resource. |
Suppliers v3
Supplier companies provide travel services to users. The Suppliers resource can be used to retrieve information about suppliers.
Retrieve all suppliers based on search criteria
GET /api/v3.0/common/suppliers/
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
name |
query |
string |
Name |
address |
query |
string |
Address |
address2 |
query |
string |
Address |
city |
query |
string |
City |
state |
query |
string |
State |
zip |
query |
string |
Zip |
country |
query |
string |
Country Code |
phone |
query |
string |
Phone |
mcCode |
query |
string |
MCC Code (Ex: Delta Airline - 3058) |
taxId |
query |
string |
Tax Id |
merchantType |
query |
string |
Merchant Type Code(Ex: Visa - VI, Amex - AX) |
merchantID |
query |
string |
Merchant Id |
iataCode |
query |
string |
IATA Code |
relevance |
query |
Int32 |
Relevance of the Search results5 |
Retrieve a single supplier by ID
GET /api/v3.0/common/suppliers/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required Supplier ID. |
Suppliers v3 - Schema
Suppliers
| Name | Type | Format | Description |
|---|---|---|---|
Items |
Array |
Supplier | The result connection |
NextPage |
string |
- | The URI of the next page of results, if any. |
Supplier
| Name | Type | Format | Description |
|---|---|---|---|
AmadeusId |
string |
- | Amadeus Id |
AustinTetra |
string |
- | Austin Tetra |
BusinessName |
string |
- | Name |
ChainCode |
string |
- | Chain Code |
ChainName |
string |
- | Chain Name |
City |
string |
- | City |
CountryCode |
string |
- | Country Code |
CreditCardVendorId |
string |
- | Creditcard Vendor Id |
DunsNumber |
string |
- | Duns Number |
Email |
string |
- | |
Fax |
string |
- | Fax |
GalileoId |
string |
- | Galileo Id |
ID |
string |
- | The unique identifier of the resource. |
MccCode |
string |
- | MCC Code (Ex: Delta Airline - 3058) |
NorthstarId |
string |
- | Northstar Id |
PegasusId |
string |
- | Pegasus Id |
Phone |
string |
- | Phone |
PostalCode |
string |
- | Zip |
PrimaryNaics |
string |
- | Primary Naics Code |
PrimarySic |
string |
- | Primary Sic Code |
PropertyCode |
string |
- | SUP_PARAM_PROPERTY_CODE |
SabreId |
string |
- | Sabre Id |
SecondaryNaics |
string |
- | Secondary Naics Code |
SecondarySic |
string |
- | Secondary Sic Code |
State |
string |
- | State |
StreetAddress |
string |
- | Address |
StreetAddress2 |
string |
- | Address2 |
TaxId |
string |
- | Tax Id |
TollFree |
string |
- | Toll Free |
URI |
string |
- | The URI to the resource. |
WebUrl |
string |
- | Web Address |
WorldspanId |
string |
- | Worldspan Id |
Direct Connect-Ground Transportation v.1
Direct Connect - Ground Transportation
The Ground Transportation Direct Connect provides a method for Travel users to access the inventory of ground transportation service providers. This direct connect was originally designed for use by limo service providers, but can be used with all forms of ground transportation.
Once the ground transportation supplier has developed their interface with SAP Concur, their inventory will begin appearing in ground transportation searches by opted-in Travel users.
This callout differs from the inbound SAP Concur web services in the following ways:
- It uses an outbound message where Travel calls a public facing API endpoint provided by the ground transportation supplier.
- The supplier configures and maintains the public web service interface. This guide specifies the request and response format required by SAP Concur.
NOTE: This direct connect was originally designed to work with Limo providers, but can support all types of ground transportation.
- Products and Editions
- Product Restrictions
- Configuration Process
- Authentication
- Operations
- GDS Sell Formats
Ground Transportation - Products and Editions
- Concur Travel Professional Edition
- Concur Travel Standard Edition
Ground Transportation - Product Restrictions
This direct connect is only available to Travel Suppliers with Ground Transportation inventory. This direct connect is not supported in the SAP Concur mobile application.
SAP Concur products are highly configurable, and not all clients will have access to all features.
Partner developers must determine which configurations are required for their solution prior to the review process.
Configuration Process
The configuration process has the following steps:
- The Travel Supplier creates the application on their system that will accept the requests from SAP Concur and return the appropriate responses.
- The Travel Supplier creates the endpoint on their system that SAP Concur uses to access their inventory.
- SAP Concur creates a production company for the travel supplier.
- The Travel Supplier registers their application with SAP Concur by logging in to their production company.
- SAP Concur configures Travel to send requests to the endpoint.
- The Travel client opts in to the Ground Transportation callout using the Travel Configuration UI to allow their users to view and book the available inventory. Clients must contact SAP Concur to have this setting activated
Once the configuration is complete, the callout uses the following process:
- The user searches for ground transportation when creating an itinerary in Travel.
- Travel sends the search details to the endpoint, using the Post Search Request.
- The supplier returns the search results.
- If the user chooses to reserve the ride, Travel sends the Post Sell Request.
- The supplier returns the Post Sell Reply.
This callout can also be used to perform the following operations:
- Get the Reservation Details
- Cancel the Ground Transportation Reservation
- Update the Ground Transportation Reservation with the Supplier
- Update the Ground Transportation Reservation with Travel
Ground Transportation - Authentication
Authentication between SAP Concur and the application connector is performed using OAuth.
Operations
Post Reservation Detail Search
Update Reservation with the Supplier
Update Reservation with Travel
GDS Sell Formats
Sabre:
1 OTH LM 14MAY M GK1 DCA/PCI QA TEST/TEL 201 555 1212/RATE-$0.00/CONF-/PICKUP-209 MADISON ST SUITE 400 ALEXANDRIAVA 22314 AT 0900/DROPOFF-DCA AIRPORT AT 0915/203121365/RESERVATION L1
Apollo:
1 LIM ZM GK1 DCA 09MAY-/PCI QA TEST-TEL 2015551212/RATE-$0.00/CONF-/PICKUP-209 MADISON ST SUITE 400"ALEXANDRIA"VA"22314 AT 0900/DROPOFF-DCA AIRPORT/52695871/RESERVATION L1
Abacus:
1 OTH LM 14MAY M GK1 DCA/PCI QA TEST/TEL 201 555 1212/RATE-$0.00/CONF-/PICKUP-209 MADISON ST SUITE 400 ALEXANDRIAVA 22314 AT 0900/DROPOFF-DCA AIRPORT AT 0915/203121365/RESERVATION L1
Galileo:
TUR ZM AK1 SEA 15DEC-/FALCON DES-TEL 8666932526/RATE-50.00 HOURLY-2 HR MIN/CONF-/PU-18400 AT 0900/DO-SEA/771297634/RES
Amadeus:
2 MIS 1A HK1 LGA 13SEP-LMO CAPITAL LIMOUSINE/TEL-800 225 1656/RATE-USD24.00 FLAT/CONF-132625/PICKUP-55 WALL STREET NEW YORK NY 10005 AT 0530/DROPOFF- LGA AIRPORT AT 0600/RID-132625760
Cancel a reservation
The Cancel Reservation operation is sent to the supplier to cancel a travel reservation on behalf of a user. The Ground Transportation direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is: https://{servername}/concur/groundtransportation. This URI is configured by the supplier when registering the partner application.
Request
URI
/concur/groundtransportation
Headers
Content-Type header (optional)
- application/xml
Accept header (optional)
- application/xml
Authorization header (required)
The Authorization header must include Base64 encoded basic authentication credentials (login ID and password). The login and password are established when the application connector is registered.
'Authorization: Basic {Base64 encoded LoginID:Password}'
Request Body
The request contains a CC_LimoCancelRequest parent element with the child elements listed in the following table:
| Element | Required/Optional | Description |
|---|---|---|
| ReservationID | Required | The unique identifier for the reservation. |
Example Request
POST /concur/groundtransportation HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoCancelRequest>
<ReservationID>1234</ReservationID>
</CC_LimoCancelRequest>
Response
The supplier responds to the request by supplying the full reservation details, with the updated status.
Content Type
- application/xml
Cancel A Reservation - Response Schema
The response will include a CC_LimoCancelReply parent element, with the following child elements:
| Element | Required? | Description |
|---|---|---|
| Error | Y | The error information, if an error occurred. This parent element contains the following child elements: ErrorCode: The code for the error. Will contain one of the following values: 400: Credential related error 800: Reservation cannot be cancelled 900: Unknown error ErrorSource: The source of the error. ErrorDescription:The additional error information. |
| ReservationID | N | The identifier for the reservation. |
| Status | N | The status of the reservation. The value will be one of the following: XB: Cancellation Requested XA: Cancellation Accepted XD: Cancellation Declined |
| ConfNum | N | The confirmation number for the reservation. |
| CancelPolicy | N | The cancellation policy for the reservation. |
| CancelNum | N | The cancellation number for the reservation. |
| PrimaryPassenger | Y | The passenger contact name for the reservation. This parent element contains the following child elements: FirstName: The contact's first name. LastName: The contact's last name. Phone: The contact's phone number. Phone2: The contact's backup phone number. CellPhone: The contact's cell phone number. EmailAddress: The contact's email address. |
| ServiceType | Y | The type of service requested. Will contain one of the following values: 100: Point to point 110: One way to airport 111: One way from airport 120: One way to train station 121: One way from train station 200: Hourly 300: Airport to airport |
| ClassOfService | N | The requested service class. Will contain one of the following values: 100: Normal 200: High 300: Highest If this value is not provided by the user, it will default to 100. |
| PickupLocation | Y | The pick up location. This parent element contains the following child elements: LocationType: One of the following: 100 - Address, 200 - Airport, 300 - Train station. Airport: Refer to the Airport Elements table. Provided if the LocationType = 200. TrainStation: Refer to the Train Station Elements table. Provided if the LocationType = 300. Address: The street address of the location. Provided if the LocationType = 100. City: The location city. State: The location state. Preferably 2 characters, max 10 characters. Country: The location's 2 character ISO 3166-1 alpha-2 country code. Example: US PostalCode: The location postal code. ExtraNotes: Additional notes about the location. Example: Ring doorbell, Holiday Inn, etc. |
| DropoffLocation | Y | The drop off location. This parent element contains the following child elements: LocationType: One of the following: 100 - Address, 200 - Airport, 300 - Train station, 400 - As directed. Airport: Refer to the Airport Elements table. Provided if the LocationType = 200. TrainStation: Refer to the Train Station Elements table. Provided if the LocationType = 300. Address: The street address of the location. Provided if the LocationType = 100. City: The location city. State: The location state. Country: The location's 2 character ISO 3166-1 alpha-2 country code. Example: US PostalCode: The location postal code. ExtraNotes: Additional notes about the location. Example: Apartment Building, gravel driveway, etc. |
| StartDateTime | Y | The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00 |
| EndDateTime | N | The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00 |
| PickupInstructions | N | Additional instructions about the pick up request. |
| DropoffInstructions | N | Additional instructions about the drop off request. |
| LanguageCode | Y | The language of the traveler. Will be one of the following options: en: English en-us: English (US) en-gb: English (UK) fr: French fr-ca: French (Canadian) de: German pt: Portuguese es: Spanish nl: Dutch it: Italian ja: Japanese pl: Polish pt-br: Portuguese (Brazilian) ru: Russian hu: Hungarian ko: Korean sv: Swedish zh-cn: Chinese zh-tw: Traditional Chinese |
| Currency | Y | The 3-letter ISO 4217 currency code for the reservation amount. |
| NumPassengers | N | The number of passengers. |
| RequestedDriver | N | The name of the requested driver, if available. |
| SpecialServiceRequest | N | The details of the special service request, if available. |
| PickupServiceArrangement | N | The details of the pickup arrangement, if available. |
| DropoffServiceArrangement | N | The details of the dropoff arrangement, if available. |
| ExtraStopArrangement | N | The details of the extra stop arrangement, if available. |
| RateInfo | Y | The booked rate details. Refer to the Rate Information Elements table for more information. |
| Vehicle | Y | The vehicle details. This parent element contains the following child elements: VehicleType: One of the following values: 100: Sedan 200: Limo 250: Stretch Limo 300: SUV 350: Stretch SUV 400: Van 450: Mini-Bus 500: Motor Coach 600: Shuttle 700: Trolley 800: Carriage 900: Any Description: The vehicle description. MaxPassengers: The maximum number of passengers for the vehicle. Must be greater than zero. VehicleID: Information to identify the specific vehicle. |
| Vendor | Y | The reservation vendor. This parent element contains the following child elements: VendorCode: The vendor code for the vendor. VendorName: The vendor's name. PhoneNumber: The vendor's phone number. |
| FormOfPayment | Y | The form of payment for the reservation. This parent element contains one of the following child elements: CreditCard: If present, the passenger will pay with credit card. Refer to the Reply Credit Card Elements table for the child elements. Cash: If present, the passenger will pay cash. Check: If present, the passenger will pay with a check. DirectBilling: If present, the passenger will pay through direct billing. |
| RateDisclaimer | N | Disclaimer text about the rate. |
| ProviderFeedback | N | Any additional feedback from the supplier. |
| AccountingInfo | N | The accounting information for the reservation. This parent element contains the following child elements: AccountingField1 through AccountingField5: These fields contain detailed accounting information. |
Rate Information Elements
| Element | Required? | Description |
|---|---|---|
| RateID | Y | The rate identifier. |
| Rate | Y | The BasePrice + ServiceCharge + SurCharge + Tax |
| RateTypeCode | Y | The code for the rate type. Will be one of the following options: F: Flat rate H: Hourly E: Estimated amount N: Currently not available |
| CategoryCode | N | Extra information that will be passed back during sell request to help identify the rate. |
| Currency | Y | The 3-letter ISO 4217 currency code for the rate amount. |
| NoRateText | N | Explanation of rate type. Provided if RateTypeCode = N |
| MinHours | N | The minimum number of hours for the reservation. |
| DiscountType | N | The type of discount applied. |
| BasePrice | N | The reservation price without taxes, surcharges or service charges. |
| ServiceCharge | N | The service charge for the reservation. |
| SurCharge | N | This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel"> |
| Tax | N | The reservation tax. |
| ExtraPickupCharge | N | Any additional fees for the pickup service. |
| ExtraDropoffCharge | N | Any additional fees for the dropoff service. |
| OptionalExtraStopCharge | N | The charge for any additional stops. |
| OptionalExtraTimeCharge | N | The charge for each additional hour. |
Reply Credit Card Elements
| Element | Required? | Description |
|---|---|---|
| Type | Y | The card type. |
| Number | Y | The card number. |
| Expiration | Y | The card expiration date. Format: 2013-02-19 |
Cancel A Reservation - Example of Successful Response
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoCancelReply>
<Error>
<ErrorCode />
<ErrorSource />
<ErrorDescription />
</Error>
<ReservationID>1234</ReservationID>
<Status>XB</Status>
<ConfNum>4444</ConfNum>
<CancelPolicy />
<CancelNum>55555</CancelNum>
<PrimaryPassenger>
<FirstName>Chris</FirstName>
<LastName>Miller</LastName>
<Phone>5551234567</Phone>
<Phone2>5551234568</Phone2>
<CellPhone>5551234569</CellPhone>
<EmailAddress>cmiller@example.com</EmailAddress>
</PrimaryPassenger>
<ServiceType>110</ServiceType>
<ClassOfService />
<PickupLocation>
<LocationType>100</LocationType>
<Airport>
<AirportCode />
<Flight>
<CarrierCode />
<FlightNumber />
<ArrivalDateTime />
</Flight>
</Airport>
<TrainStation>
<StationCode />
<StationName />
<City />
<State />
<Train>
<CarrierCode />
<CarrierName />
<TrainNumber />
<ArrivalDateTime />
</Train>
</TrainStation>
<Address>209 Madison St</Address>
<City>Alexandria</City>
<State>VA</State>
<Country>US</Country>
<PostalCode>22314</PostalCode>
<ExtraNotes />
</PickupLocation>
<DropoffLocation>
<LocationType>200</LocationType>
<Airport>
<AirportCode>DCA</AirportCode>
<Flight>
<CarrierCode>UA</CarrierCode>
<FlightNumber>333</FlightNumber>
<DepartureDateTime>2012-02-19T11:29:00</DepartureDateTime>
</Flight>
</Airport>
<TrainStation>
<StationCode />
<StationName />
<City />
<State />
<Train>
<CarrierCode />
<CarrierName />
<TrainNumber />
<DepartureDateTime />
</Train>
</TrainStation>
<Address />
<City />
<State />
<Country />
<PostalCode />
<ExtraNotes />
</DropoffLocation>
<StartDateTime>2012-02-19T09:00:00</StartDateTime>
<EndDateTime />
<PickupInstructions>pick me up</PickupInstructions>
<DropoffInstructions>None</DropoffInstructions>
<LanguageCode>en-us</LanguageCode>
<Currency>USD</Currency>
<NumPassengers>1</NumPassengers>
<RequestedDriver />
<SpecialServiceRequest />
<PickupServiceArrangement />
<DropoffServiceArrangement />
<ExtraStopArrangement />
<RateInfo>
<RateID>5</RateID>
<Rate>42.50</Rate>
<RateTypeCode>E</RateTypeCode>
<CategoryCode />
<MinHours />
<Currency>US</Currency>
<NoRateText />
<DiscountType />
<BasePrice>35.00</BasePrice>
<ServiceCharge>5.00</ServiceCharge>
<SurCharge desc="fuel">1.00</SurCharge>
<Tax>1.50</Tax>
<ExtraPickupCharge />
<ExtraDropoffCharge />
<OptionalExtraStopCharge />
<OptionalExtraTimeCharge />
<Message />
</RateInfo>
<RateDisclaimer />
<Vehicle>
<VehicleType>100</VehicleType>
<Description>This is a Sedan.</Description>
<MaxPassengers>1</MaxPassengers>
<VehicleID>12</VehicleID>
</Vehicle>
<Vendor>
<VendorCode>LML</VendorCode>
<VendorName>LimoVendor</VendorName>
<PhoneNumber>4354654654</PhoneNumber>
</Vendor>
<ProviderFeedback />
<FormOfPayment>
<Cash />
<Check />
<DirectBilling />
<CreditCard>
<Type>VI</Type>
<Number>XXXXXXXXXXXX1111</Number>
<Expiration>2013-02-19</Expiration>
</CreditCard>
</FormOfPayment>
<AccountingInfo>
<AccountingField1>715</AccountingField1>
<AccountingField2>temp@outtask.com</AccountingField2>
<AccountingField3>11</AccountingField3>
<AccountingField4>Development</AccountingField4>
<AccountingField5/>
</AccountingInfo>
</CC_LimoCancelReply>
Post a reservation detail search
Request
The following request is sent to the supplier when the Travel user selects a ground transportation reservation to get additional details.
URI
The Ground Transportation direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:
https://{servername}/concur/groundtransportation
The URI is configured by the supplier when registering the partner application.
Request Headers - Required
Authorization header with OAuth credentials. Refer to the OAuth documentation for more information.
Request Headers - Optional
None
Request Body
The request will contain a CC_LimoReservationDetailRequest parent element, containing the following child element:
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| ReservationID | The unique identifier for the reservation. Returned in the ReservationID element by the response of the Post Reservation Sell function. |
XML Example Request
POST /concur/groundtransportation HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoReservationDetailRequest>
<ReservationID>1234</ReservationID>
</CC_LimoReservationDetailRequest>
Response
The supplier responds to the request by supplying the full reservation details.
Content Type
application/xml
Post a reservation detail search - Response Schema
The response will include a CC_LimoReservationDetailReply parent element, with the following child elements:
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| Error | Y | The error information, if an error occurred. For information about the child elements of this parent element, see the Error elements table. | |
| ReservationID | N | The identifier for the reservation. | |
| Status | N | The status of the reservation. The value will be one of the following: RB: Reservation Pending RA: Reservation Accepted (Reserved) RD: Reservation Declined XB: Cancellation Pending XA: Cancellation Confirmed (Cancelled) XD: Cancellation Declined |
|
| ConfNum | N | The confirmation number for the reservation. | |
| CancelPolicy | N | The cancellation policy for the reservation. | |
| CancelNum | N | The cancellation number for the reservation. | |
| PrimaryPassenger | Y | The passenger contact name for the reservation. For information about the child elements of this parent element, see the PrimaryPassenger elements table. | |
| ServiceType | Y | The type of service requested. Will contain one of the following values: 100: Point to point 110: One way to airport 111: One way from airport 120: One way to train station 121: One way from train station 200: Hourly 300: Airport to airport |
|
| ClassOfService | N | The requested service class. Will contain one of the following values: 100: Normal 200: High 300: Highest If this value is not provided by the user, it will default to 100. |
|
| PickupLocation | Y | The pick up location. For information about the child elements of this parent element, see the PickupLocation elements table. | |
| DropoffLocation | Y | The drop off location. For information about the child elements of this parent element, see the DropoffLocation elements table. | |
| StartDateTime | Y | The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00 | |
| EndDateTime | N | The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00 | |
| PickupInstructions | N | Additional instructions about the pick up request. | |
| DropoffInstructions | N | Additional instructions about the drop off request. | |
| LanguageCode | Y | The language of the traveler. Will be one of the following options: en: English en-us: English (US) en-gb: English (UK) fr: French fr-ca: French (Canadian) de: German pt: Portuguese es: Spanish nl: Dutch it: Italian ja: Japanese pl: Polish bt-br: Portuguese (Brazilian) ru: Russian hu: Hungarian ko: Korean sv: Swedish zh-cn: Chinese zh-tw: Traditional Chinese |
|
| Currency | Y | The 3-letter ISO 4217 currency code for the reservation amount. | |
| NumPassengers | N | The number of passengers. | |
| RequestedDriver | N | The name of the requested driver, if available. | |
| SpecialServiceRequest | N | The details of the special service request, if available. | |
| PickupServiceArrangement | N | The details of the pickup arrangement, if available. | |
| DropoffServiceArrangement | N | The details of the dropoff arrangement, if available. | |
| ExtraStopArrangement | N | The details of the extra stop arrangement, if available. | |
| RateInfo | Y | The booked rate details. Refer to the Rate Information elements table for more information. | |
| Vehicle | Y | The vehicle details. For information about the child elements of this parent element, see the Vehicle elements table. | |
| Vendor | Y | The reservation vendor. For information about the child elements of this parent element, see the Vendor elements table. | |
| FormOfPayment | Y | The form of payment for the reservation. For information about the child elements of this parent element, see the FormOfPayment elements table. | |
| RateDisclaimer | N | Disclaimer text about the rate. | |
| ProviderFeedback | N | Any additional feedback from the supplier. | |
| AccountingInfo | N | The accounting information for the reservation. This parent element contains the following child elements: AccountingField1 through AccountingField5 |
Error Child Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| ErrorCode | The code for the error. Will contain one of the following values: 400: Credential related error 700: Reservation not available 900: Unknown error |
||
| ErrorSource | The source of the error. | ||
| ErrorDescription | The additional error information. |
PrimaryPassenger Child Element
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| FirstName | The contact's first name. | ||
| LastName | The contact's last name. | ||
| Phone | The contact's phone number. | ||
| Phone2 | The contact's backup phone number. | ||
| CellPhone | The contact's cell phone number. | ||
| EmailAddress | The contact's email address. |
PickupLocation
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| LocationType | One of the following: 100 - Address, 200 - Airport, 300 - Train station. | ||
| Airport | Refer to the Airport elements table. Provided if the LocationType = 200. | ||
| TrainStation | Refer to the Train Station elements table. Provided if the LocationType = 300. | ||
| Address | The street address of the location. Provided if the LocationType = 100. | ||
| City | The location city. | ||
| State | The location state. Preferably 2 characters, max 10 characters. | ||
| Country | The location's 2 character ISO 3166-1 alpha-2 country code. Example: US | ||
| PostalCode | The location postal code. | ||
| ExtraNotes | Additional notes about the location. Example: Ring doorbell, Holiday Inn, etc. |
DropoffLocation
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| LocationType | One of the following: 100 - Address, 200 - Airport, 300 - Train station, 400 - As directed. | ||
| Airport | Refer to the Airport elements table. Provided if the LocationType = 200. | ||
| TrainStation | Refer to the Train Station elements table. Provided if the LocationType = 300. | ||
| Address | The street address of the location. Provided if the LocationType = 100. | ||
| City | The location city. | ||
| State | The location state. Preferably 2 characters, max 10 characters. | ||
| Country | The location's 2 character ISO 3166-1 alpha-2 country code. Example: US | ||
| PostalCode | The location postal code. | ||
| ExtraNotes | Additional notes about the location. Example: Apartment Building, gravel driveway, etc. |
Vehicle Child Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| VehicleType | One of the following values: 100: Sedan 200: Limo 250: Stretch Limo 300: SUV 350: Stretch SUV 400: Van 450: Mini-Bus 500: Motor Coach 600: Shuttle 700: Trolley 800: Carriage 900: Any |
||
| Description | The vehicle description. | ||
| MaxPassengers | The maximum number of passengers for the vehicle. Must be greater than zero. | ||
| VehicleID | Information to identify the specific vehicle. |
Vendor Child Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| VendorCode | The vendor code for the vendor. | ||
| VendorName | The vendor's name. | ||
| PhoneNumber | The vendor's phone number. |
FormOfPayment Child Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| CreditCard | If present, the passenger will pay with credit card. Refer to the Reply Credit Card Elements table for the child elements. | ||
| Cash | If present, the passenger will pay cash. | ||
| Check | If present, the passenger will pay with a check. | ||
| DirectBilling | If present, the passenger will pay through direct billing. |
Post a reservation - Rate Information Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| RateID | Y | The rate identifier. | |
| Rate | Y | The BasePrice + ServiceCharge + SurCharge + Tax | |
| RateTypeCode | Y | The code for the rate type. Will be one of the following options: F: Flat rate H: Hourly E: Estimated amount N: Currently not available |
|
| CategoryCode | N | Extra information that will be passed back during sell request to help identify the rate. | |
| Currency | Y | The 3-letter ISO 4217 currency code for the rate amount. | |
| NoRateText | N | Explanation of rate type. Provided if RateTypeCode = N | |
| MinHours | N | The minimum number of hours for the reservation. | |
| DiscountType | N | The type of discount applied. | |
| BasePrice | N | The reservation price without taxes, surcharges or service charges. | |
| ServiceCharge | N | The service charge for the reservation. | |
| SurCharge | N | This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel"> |
|
| Tax | N | The reservation tax. | |
| ExtraPickupCharge | N | Any additional fees for the pickup service. | |
| ExtraDropoffCharge | N | Any additional fees for the drop off service. | |
| OptionalExtraStopCharge | N | The charge for any additional stops. | |
| OptionalExtraTimeCharge | N | The charge for each additional hour. |
Post a reservation - Reply Credit Card Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| Type | Y | The card type. | |
| Number | Y | The card number. | |
| Expiration | Y | The card expiration date. Format: 2013-02-19. |
Airport Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| AirportCode | The IATA code for the airport. | ||
| Flight | The flight information. For information about the child elements of this parent element, see the Flight elements table. |
Flight Child Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| CarrierCode | The airline code. | ||
| FlightNumber | The flight number. | ||
| ArrivalDateTime | The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 | ||
| DepartureDateTime | The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00 |
Train Station Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| StationCode | The station code. | ||
| StationName | The name of the station. | ||
| City | The city the station is located in. | ||
| State | The state the station is located in. Preferably 2 characters, max 10 characters. | ||
| Train | The train information. For information about the child elements of this parent element, see the Train elements table. |
Train Child Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| CarrierCode | The code of the train carrier. | ||
| CarrierName | The name of the train carrier. | ||
| TrainNumber | The train number. | ||
| ArrivalDateTime | The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 | ||
| DepartureDateTime | The train departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00 |
Post Reservation - XML Example of Successful Response
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoReservationDetailReply>
<Error>
<ErrorCode />
<ErrorSource />
<ErrorDescription />
</Error>
<ReservationID>1234</ReservationID>
<Status>RB</Status>
<ConfNum>4444</ConfNum>
<CancelPolicy />
<CancelNum>55555</CancelNum>
<PrimaryPassenger>
<FirstName>Chris</FirstName>
<LastName>Miller</LastName>
<Phone>5551234567</Phone>
<Phone2>5551234568</Phone2>
<CellPhone>5551234569</CellPhone>
<EmailAddress>cmiller@example.com</EmailAddress>
</PrimaryPassenger>
<ServiceType>110</ServiceType>
<ClassOfService />
<PickupLocation>
<LocationType>100</LocationType>
<Airport>
<AirportCode />
<Flight>
<CarrierCode />
<FlightNumber />
<ArrivalDateTime />
</Flight>
</Airport>
<TrainStation>
<StationCode />
<StationName />
<City />
<State />
<Train>
<CarrierCode />
<CarrierName />
<TrainNumber />
<ArrivalDateTime />
</Train>
</TrainStation>
<Address>209 Madison St</Address>
<City>Alexandria</City>
<State>VA</State>
<Country>US</Country>
<PostalCode>22314</PostalCode>
<ExtraNotes />
</PickupLocation>
<DropoffLocation>
<LocationType>200</LocationType>
<Airport>
<AirportCode>DCA</AirportCode>
<Flight>
<CarrierCode>UA</CarrierCode>
<FlightNumber>333</FlightNumber>
<DepartureDateTime>2012-02-19T11:29:00</DepartureDateTime>
</Flight>
</Airport>
<TrainStation>
<StationCode />
<StationName />
<City />
<State />
<Train>
<CarrierCode />
<CarrierName />
<TrainNumber />
<DepartureDateTime />
</Train>
</TrainStation>
<Address />
<City />
<State />
<Country />
<PostalCode />
<ExtraNotes />
</DropoffLocation>
<StartDateTime>2012-02-19T09:00:00</StartDateTime>
<EndDateTime />
<PickupInstructions>pick me up</PickupInstructions>
<DropoffInstructions>None</DropoffInstructions>
<LanguageCode>en-us</LanguageCode>
<Currency>USD</Currency>
<NumPassengers>1</NumPassengers>
<RequestedDriver />
<SpecialServiceRequest />
<PickupServiceArrangement />
<DropoffServiceArrangement />
<ExtraStopArrangement />
<RateInfo>
<RateID>5</RateID>
<Rate>42.50</Rate>
<RateTypeCode>E</RateTypeCode>
<CategoryCode />
<MinHours />
<Currency>USD</Currency>
<NoRateText />
<DiscountType />
<BasePrice>35.00</BasePrice>
<ServiceCharge>5.00</ServiceCharge>
<SurCharge desc="fuel">1.00</SurCharge>
<Tax>1.50</Tax>
<ExtraPickupCharge />
<ExtraDropoffCharge />
<OptionalExtraStopCharge />
<OptionalExtraTimeCharge />
<Message />
</RateInfo>
<RateDisclaimer />
<Vehicle>
<VehicleType>100</VehicleType>
<Description>This is a Sedan.</Description>
<MaxPassengers>1</MaxPassengers>
<VehicleID>12</VehicleID>
</Vehicle>
<Vendor>
<VendorCode>LML</VendorCode>
<VendorName>LimoVendor</VendorName>
<PhoneNumber>4354654654</PhoneNumber>
</Vendor>
<ProviderFeedback />
<FormOfPayment>
<Cash />
<Check />
<DirectBilling />
<CreditCard>
<Type>VI</Type>
<Number>XXXXXXXXXXXX1111</Number>
<Expiration>2013-02-19</Expiration>
</CreditCard>
</FormOfPayment>
<AccountingInfo>
<AccountingField1>715</AccountingField1>
<AccountingField2>temp@outtask.com</AccountingField2>
<AccountingField3>11</AccountingField3>
<AccountingField4>Development</AccountingField4>
<AccountingField5/>
</AccountingInfo>
</CC_LimoReservationDetailReply>
Post a reservation sell request
A post reservation sell request is sent when a Travel user attempts to book a ground transportation reservation.
Post A Reservation Sell Request - Request
Supported Accept Types
application/xml
Request URI
The Ground Transportation direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:
https://{servername}/concur/groundtransportation
The URI is configured by the supplier when registering the partner application.
Headers
Authorization Header
Authentication header with Base64 encoded basic authentication credentials (login ID and password) is required. The basic authentication credentials are established during the application review process.
Authorization: Basic {Base64 encoded LoginID:Password}
Post Reservation - Request Body
The request will contain a CC_LimoSellRequest parent element, containing the following child elements.
CorporateClient
The corporate client the booking is on behalf of. This parent element contains the following child element:
- CompanyCode: The code for the company of the client.
Booker
The user booking the reservation. This parent element contains the following child elements:
- UserID: The user's SAP Concur user ID.
- EmailAddress: The user's email address.
- Phone: The user's contact number.
PrimaryPassenger
The passenger contact name for the reservation. This parent element contains the following child elements:
- FirstName: The contact's first name
- LastName: The contact's last name
- Phone: The contact's phone number
- Phone2: The contact's backup phone number
- CellPhone: The contact's cell phone number
- EmailAddress: The contact's email address
ServiceType
The type of service requested. Will contain one of the following values:
- 100: Point to point
- 110: One way to airport
- 111: One way from airport
- 120: One way to train station
- 121: One way from train station
- 200: Hourly
- 300: Airport to airport
ClassOfService
The requested service class. Will contain one of the following values:
- 100: Normal
- 200: High
- 300: Highest
If this value is not provided by the user, it will default to 100
PickupLocation
The pick up location. This parent element contains the following child elements:
- LocationType: One of the following: 100 - Address, 200 - Airport, 300 - Train station.
- Airport: Refer to the Airport elements table. Provided if the LocationType = 200.
- TrainStation: Refer to the Train Station elements table. Provided if the LocationType = 300.
- Address: The street address of the location. Provided if the LocationType = 100.
- City: The location city.
- State: The location state. Preferably 2 characters, max 10 characters.
- Country: The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
- PostalCode: The location postal code.
- ExtraNotes: Additional notes about the location. Example: Ring doorbell, Holiday Inn, etc.
DropoffLocation
The drop off location. This parent element contains the following child elements:
- LocationType: One of the following: 100 - Address, 200 - Airport, 300 - Train station, 400 - As directed.
- Airport: Refer to the Airport elements table. Provided if the LocationType = 200.
- TrainStation: Refer to the Train Station elements table. Provided if the LocationType = 300.
- Address: The street address of the location. Provided if the LocationType = 100.
- City: The location city.
- State: The location state. Preferably 2 characters, max 10 characters.
- Country: The location's 2 character ISO 3166-1 alpha-2 country code. Example: US
- PostalCode: The location postal code.
- ExtraNotes: Additional notes about the location. Example: Apartment Building, gravel driveway, etc.
StartDateTime
The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00
EndDateTime
The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00
PickupInstructions
Additional instructions about the pick up request.
DropoffInstructions
Additional instructions about the drop off request.
LanguageCode
The language of the traveler. Will be one of the following options:
- en: English
- en-us: English (US)
- en-gb: English (UK)
- fr: French
- fr-ca: French (Canadian)
- de: German
- pt: Portuguese
- es: Spanish
- nl: Dutch
- it: Italian
- ja: Japanese
- pl: Polish
- pt-br: Portuguese (Brazilian)
- ru: Russian
- hu: Hungarian
- ko: Korean
- sv: Swedish
- zh-cn: Chinese
- zh-tw: Traditional Chinese
Currency
The 3-letter ISO 4217 currency code for the reservation amount.
NumPassengers
The number of passengers.
DiscountCode
The discount code information. This parent element contains the following child elements:
- Corporate ID: The user's corporate ID.
- VendorCode: The user's vendor code.
- DiscountNumber: The user's discount number.
RateInfo
The booked rate. This parent element contains the following child elements:
- RateID: The rate identifier.
- Rate: The total rate, including the BasePrice, ServiceCharge, SurCharge, and Tax.
- RateTypeCode: The code for the rate type. Will be one of the following options:
- F: Flat rate
- H: Hourly
- E: Estimated amount
- N: Currently not available
- CategoryCode Extra information that will be passed back during sell request to help identify the rate.
- Currency The 3-letter ISO 4217 currency code for the rate amount.
Vehicle
The vehicle details. This parent element contains the following child elements:
VehicleType: One of the following values:
- 100: Sedan
- 200: Limo
- 250: Stretch Limo
- 300: SUV
- 350: Stretch SUV
- 400: Van
- 450: Mini-Bus
- 500: Motor Coach
- 600: Shuttle
- 700: Trolley
- 800: Carriage
- 900: Any
VehicleID: Information to identify the specific vehicle.
Vendor
The reservation vendor. This parent element contains the following child element:
- VendorCode: The vendor code for the vendor.
FormOfPayment
The form of payment for the reservation. This parent element contains one of the following child elements:
- CreditCard: If present, the passenger will pay with credit card. Refer to the Reply Credit Card elements table for the child elements.
- Cash: If present, the passenger will pay cash.
- Check: If present, the passenger will pay with a check.
- DirectBilling: If present, the passenger will pay through direct billing.
RequestedDriver
The name of the requested driver, if available.
SpecialServiceRequest
The details of the special service request, if available.
PickupServiceArrangement
The details of the pickup arrangement, if available.
DropoffServiceArrangement
The details of the dropoff arrangement, if available.
ExtraStopArrangement
The details of the extra stop arrangement, if available.
RequestedDriver
The name of the requested driver, if available.
Post Reservation - Airport Elements
AirportCode
The IATA code for the airport.
Flight: The flight information. This parent element contains the following child elements: * CarrierCode: The airline code. * FlightNumber: The flight number. * ArrivalDateTime: The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 * DepartureDateTime: The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00
Post Reservation - Train Station Elements
StationCode
The station code.
StationName
The name of the station.
City
The city the station is located in.
State
The state the station is located in. Preferably 2 characters, max 10 characters.
Train
The train information. This parent element contains the following child elements:
- CarrierCode: The code of the train carrier.
- CarrierName: The name of the train carrier.
- TrainNumber: The train number.
- ArrivalDateTime: The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
- DepartureDateTime: The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00
Post A Reservation Sell Request - Credit Card Elements
Type
The card type.
Number
The card number.
Expiration
The card expiration date. Format: 2013-02-19
Name
The name on the card.
Address
The street information of the billing address of the car.
City
The city of the billing address of the car.
State
The state of the billing address of the car. Preferably 2 characters, max 10 characters.
Country
The country of the billing address of the car.
PostalCode
The postal code of the billing address of the car.
Post A Reservation Sell - XML Example Request
POST /concur/groundtransportation HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoSellRequest>
<CorporateClient>
<CompanyCode>339</CompanyCode>
</CorporateClient>
<Booker>
<UserID>55414</UserID>
<EmailAddress>cmiller@example.com</EmailAddress>
<Phone>5551234567</Phone>
</Booker>
<PrimaryPassenger>
<FirstName>Chris</FirstName>
<LastName>Miller</LastName>
<Phone>5551234567</Phone>
<Phone2>5551234568</Phone2>
<CellPhone>5551234569</CellPhone>
<EmailAddress>cmiller@example.com</EmailAddress>
</PrimaryPassenger>
<ServiceType>110</ServiceType>
<ClassOfService>100</ClassOfService>
<StartDateTime>2012-02-19T09:00:00</StartDateTime>
<EndDateTime />
<PickupInstructions>pick me up</PickupInstructions>
<DropoffInstructions>None</DropoffInstructions>
<LanguageCode>en-us</LanguageCode>
<RateInfo>
<RateID>1</RateID>
<Rate>42.50</Rate>
<RateTypeCode>100</RateTypeCode>
<CategoryCode />
<Currency>USD</Currency>
</RateInfo>
<Vehicle>
<VehicleType>Sedan</VehicleType>
<Description>This is a Sedan.</Description>
<MaxPassengers>1</MaxPassengers>
<VehicleID>12</VehicleID>
</Vehicle>
<Vendor>
<VendorCode>LML</VendorCode>
<VendorName>LimoVendor</VendorName>
<PhoneNumber>4354654654</PhoneNumber>
</Vendor>
<FormOfPayment>
<CreditCard>
<Type>VI</Type>
<Number>xxxxxxxxxxxx1111</Number>
<Expiration>2013-02-19</Expiration>
<NameOnCard />
<Address>209 MADISON ST. #400</Address>
<City>ALEXANDRIA</City>
<State>VA</State>
<Country>US</Country>
<PostalCode>22314</PostalCode>
</CreditCard>
</FormOfPayment>
<RequestedDriver />
<AccountingInfo>
<AccountingField1>715</AccountingField1>
<AccountingField2>temp@outtask.com</AccountingField2>
<AccountingField3>11</AccountingField3>
<AccountingField4>Development</AccountingField4>
<AccountingField5/>
</AccountingInfo>
</CC_LimoSellRequest>
Post Reservation - Response
The supplier responds to the Sell request by returning the details of the booked reservation.
Supported Content Types
application/xml
Post Reservation - Content Body
The response will include a CC_LimoSellReply parent element, with the following child elements:
| Element | Required? | Description |
|---|---|---|
| Error | Y | The error information, if an error occurred. For information about the child elements of this parent element, see the Error elements table below. |
| ReservationID | N | The identifier for the reservation. |
| Status | N | The status of the reservation. The value will be one of the following: RB: Reservation Pending RA: Reservation Accepted (Reserved) RD: Reservation Declined |
| ConfNum | N | The confirmation number for the reservation. |
| CancelPolicy | N | The cancellation policy for the reservation. |
| CancelNum | N | The cancellation number for the reservation. |
| PrimaryPassenger | Y | The passenger contact name for the reservation. For information about the child elements of this parent element, see the PrimaryPassenger elements table below. |
| ServiceType | Y | The type of service requested. Will contain one of the following values: 100: Point to point 110: One way to airport 111: One way from airport 120: One way to train station 121: One way from train station 200: Hourly 300: Airport to airport |
| ClassOfService | N | The requested service class. Will contain one of the following values: 100: Normal 200: High 300: Highest If this value is not provided by the user, it will default to 100. |
| PickupLocation | Y | The pick up location. For information about the child elements of this parent element, see the PickupLocation elements table below. |
| DropoffLocation | Y | The drop off location. For information about the child elements of this parent element, see the DropoffLocation elements table below. |
| StartDateTime | Y | The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00 |
| EndDateTime | N | The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00 |
| PickupInstructions | N | Additional instructions about the pick up request. |
| DropoffInstructions | N | Additional instructions about the drop off request. |
| LanguageCode | Y | The language of the traveler. Will be one of the following options: en: English en-us: English (US) en-gb: English (UK) fr: French fr-ca: French (Canadian) de: German pt: Portuguese es: Spanish nl: Dutch it: Italian ja: Japanese pl: Polish pt-br: Portuguese (Brazilian) ru: Russian hu: Hungarian ko: Korean sv: Swedish zh-cn: Chinese zh-tw: Traditional Chinese |
| Currency | Y | The 3-letter ISO 4217 currency code for the reservation amount. |
| NumPassengers | N | The number of passengers. |
| RequestedDriver | N | The name of the requested driver, if available. |
| SpecialServiceRequest | N | The details of the special service request, if available. |
| PickupServiceArrangement | N | The details of the pickup arrangement, if available. |
| DropoffServiceArrangement | N | The details of the dropoff arrangement, if available. |
| ExtraStopArrangement | N | The details of the extra stop arrangement, if available. |
| RateInfo | Y | The booked rate details. Refer to the Rate Information elements table below for more information. |
| Vehicle | Y | The vehicle details. For information about the child elements of this parent element, see the Vehicle elements table below. |
| Vendor | Y | The reservation vendor. For information about the child elements of this parent element, see the Vendor elements table below. |
| FormOfPayment | Y | The form of payment for the reservation. For information about the child elements of this parent element, see the FormOfPayment elements table below. |
| RateDisclaimer | N | Disclaimer text about the rate. |
| ProviderFeedback | N | Any additional feedback from the supplier. |
| AccountingInfo | N | The accounting information for the reservation. This parent element contains one or more AccountingField elements: AccountingField1 through AccountingField5. These fields contain detailed accounting information. |
Post A Reservation Sell Request - Error Elements
| Element | Description |
|---|---|
| ErrorCode | The code for the error. Will contain one of the following values: 100: Pickup/dropoff location related error 200: Pickup/dropoff time related error 300: Other request parameters related error 400: Credential related error 500: No rate/service available 600: FOP related error 900: Unknown error |
| ErrorSource | The source of the error. |
| ErrorDescription | The additional error information. |
PrimaryPassenger Elements
| Element | Description |
|---|---|
| FirstName | The contact's first name. |
| LastName | The contact's last name. |
| Phone | The contact's phone number. |
| Phone2 | The contact's backup phone number. |
| CellPhone | The contact's cell phone number. |
| EmailAddress | The contact's email address. |
Post Reservation - Rate Information Elements
| Element Name | Required? | Data Type | Description |
|---|---|---|---|
| RateID | Y | The rate identifier. | |
| Rate | Y | The BasePrice + ServiceCharge + SurCharge + Tax | |
| RateTypeCode | Y | The code for the rate type. Will be one of the following options: F: Flat rate H: Hourly E: Estimated amount N: Currently not available |
|
| CategoryCode | N | Extra information that will be passed back during sell request to help identify the rate. | |
| Currency | Y | The 3-letter ISO 4217 currency code for the rate amount. | |
| NoRateText | N | Explanation of rate type. Provided if RateTypeCode = N | |
| MinHours | N | The minimum number of hours for the reservation. | |
| DiscountType | N | The type of discount applied. | |
| BasePrice | N | The reservation price without taxes, surcharges or service charges. | |
| ServiceCharge | N | The service charge for the reservation. | |
| SurCharge | N | This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel"> |
|
| Tax | N | The reservation tax. | |
| ExtraPickupCharge | N | Any additional fees for the pickup service. | |
| ExtraDropoffCharge | N | Any additional fees for the drop off service. | |
| OptionalExtraStopCharge | N | The charge for any additional stops. | |
| OptionalExtraTimeCharge | N | The charge for each additional hour. |
Vehicle Elements
| Element | Description |
|---|---|
| VehicleType | One of the following values: 100: Sedan 200: Limo 250: Stretch Limo 300: SUV 350: Stretch SUV 400: Van 450: Mini-Bus 500: Motor Coach 600: Shuttle 700: Trolley 800: Carriage 900: Any |
| VehicleID | Information to identify the specific vehicle. |
Vendor Elements
| Element | Description |
|---|---|
| VendorCode | The vendor code for the vendor. |
| VendorName | The vendor's name. |
| PhoneNumber | The vendor's phone number. |
FormOfPayment Elements
| Element | Description |
|---|---|
| CreditCard | If present, the passenger will pay with credit card. Refer to the Reply Credit Card elements table for the child elements. |
| Cash | If present, the passenger will pay cash. |
| Check | If present, the passenger will pay with a check. |
| DirectBilling | If present, the passenger will pay through direct billing. |
Post a reservation - Reply Credit Card Elements
| Element Name | Required? | Description |
|---|---|---|
| Type | Y | The card type. |
| Number | Y | The card number. |
| Expiration | Y | The card expiration date. Format: 2013-02-19 |
Post A Reservation Sell Request - XML Example of Successful Response
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoSellReply>
<Error>
<ErrorCode />
<ErrorSource />
<ErrorDescription />
</Error>
<ReservationID>1234</ReservationID>
<Status>RB</Status>
<ConfNum>4444</ConfNum>
<CancelPolicy />
<CancelNum>55555</CancelNum>
<PrimaryPassenger>
<FirstName>Chris</FirstName>
<LastName>Miller</LastName>
<Phone>5551234567</Phone>
<Phone2>5551234568</Phone2>
<CellPhone>5551234569</CellPhone>
<EmailAddress>cmiller@example.com</EmailAddress>
</PrimaryPassenger>
<ServiceType>110</ServiceType>
<ClassOfService />
<PickupLocation>
<LocationType>100</LocationType>
<Airport>
<AirportCode />
<Flight>
<CarrierCode />
<FlightNumber />
<ArrivalDateTime />
</Flight>
</Airport>
<TrainStation>
<StationCode />
<StationName />
<City />
<State />
<Train>
<CarrierCode />
<CarrierName />
<TrainNumber />
<ArrivalDateTime />
</Train>
</TrainStation>
<Address>209 Madison St</Address>
<City>Alexandria</City>
<State>VA</State>
<Country>US</Country>
<PostalCode>22314</PostalCode>
<ExtraNotes />
</PickupLocation>
<DropoffLocation>
<LocationType>200</LocationType>
<Airport>
<AirportCode>DCA</AirportCode>
<Flight>
<CarrierCode>UA</CarrierCode>
<FlightNumber>333</FlightNumber>
<DepartureDateTime>2012-02-19T11:29:00</DepartureDateTime>
</Flight>
</Airport>
<TrainStation>
<StationCode />
<StationName />
<City />
<State />
<Train>
<CarrierCode />
<CarrierName />
<TrainNumber />
<DepartureDateTime />
</Train>
</TrainStation>
<Address />
<City />
<State />
<Country />
<PostalCode />
<ExtraNotes />
</DropoffLocation>
<StartDateTime>2012-02-19T09:00:00</StartDateTime>
<EndDateTime />
<PickupInstructions>pick me up</PickupInstructions>
<DropoffInstructions>None</DropoffInstructions>
<LanguageCode>en-us</LanguageCode>
<Currency>USD</Currency>
<NumPassengers>1</NumPassengers>
<RequestedDriver />
<SpecialServiceRequest />
<PickupServiceArrangement />
<DropoffServiceArrangement />
<ExtraStopArrangement />
<RateInfo>
<RateID>5</RateID>
<Rate>42.50</Rate>
<RateTypeCode>E</RateTypeCode>
<CategoryCode />
<MinHours />
<Currency>US</Currency>
<NoRateText />
<DiscountType />
<BasePrice>35.00</BasePrice>
<ServiceCharge>5.00</ServiceCharge>
<SurCharge desc="fuel">1.00</SurCharge>
<Tax>1.50</Tax>
<ExtraPickupCharge />
<ExtraDropoffCharge />
<OptionalExtraStopCharge />
<OptionalExtraTimeCharge />
<Message />
</RateInfo>
<RateDisclaimer />
<Vehicle>
<VehicleType>100</VehicleType>
<Description>This is a Sedan.</Description>
<MaxPassengers>1</MaxPassengers>
<VehicleID>12</VehicleID>
</Vehicle>
<Vendor>
<VendorCode>LML</VendorCode>
<VendorName>LimoVendor</VendorName>
<PhoneNumber>4354654654</PhoneNumber>
</Vendor>
<ProviderFeedback />
<FormOfPayment>
<Cash />
<Check />
<DirectBilling />
<CreditCard>
<Type>VI</Type>
<Number>XXXXXXXXXXXX1111</Number>
<Expiration>2013-02-19</Expiration>
</CreditCard>
</FormOfPayment>
<AccountingInfo>
<AccountingField1>715</AccountingField1>
<AccountingField2>temp@outtask.com</AccountingField2>
<AccountingField3>11</AccountingField3>
<AccountingField4>Development</AccountingField4>
<AccountingField5/>
</AccountingInfo>
</CC_LimoSellReply>
Post a transportation search
A post transportation search request is sent when the Travel user searches for ground transportation.
Post a transportation search - Request
URI
The Ground Transportation direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:
https://{servername}/concur/groundtransportation
The URI is configured by the supplier when registering the partner application.
Headers
Accept Header
application/xml
Authorization Header
Authorization header with OAuth credentials.
Post a transportation search - Request Body
The request will contain a CC_LimoSearchRequest parent element, containing the following child elements.
ServiceType: The type of service requested. Will contain one of the following values:
100: Point to point
110: One way to airport
111: One way from airport
120: One way to train station
121: One way from train station
200: Hourly
300: Airport to airport
ClassOfService: The requested service class. Will contain one of the following values:
100: Normal
200: High
300: Highest
If this value is not provided by the user, it will default to 100.
PickupLocation: The pick up location. This parent element contains the following child elements:
Post a transportation search - PickupLocation Elements
| Element | Description |
|---|---|
| LocationType | One of the following: 100 - Address, 200 - Airport, 300 - Train station. |
| Airport | Refer to the Airport Elements table. Provided if the LocationType = 200. |
| TrainStation | Refer to the Train Station Elements table. Provided if the LocationType = 300. |
| Address | The street address of the location. Provided if the LocationType = 100. |
| City | The location city. |
| State | The location state. Preferably 2 characters, max 10 characters. |
| Country | The location's 2 character ISO 3166-1 alpha-2 country code. Example: US |
| PostalCode | The location postal code. |
| ExtraNotes | Additional notes about the location. Example: Ring doorbell, Holiday Inn, etc. |
DropoffLocation: The drop off location. This parent element contains the following child elements:
Post a transportation search - DropoffLocation Elements
| Element | Description |
|---|---|
| LocationType | One of the following: 100 - Address, 200 - Airport, 300 - Train station. |
| Airport | Refer to the Airport Elements table. Provided if the LocationType = 200. |
| TrainStation | Refer to the Train Station Elements table. Provided if the LocationType = 300. |
| Address | The street address of the location. Provided if the LocationType = 100. |
| City | The location city. |
| State | The location state. Preferably 2 characters, max 10 characters. |
| Country | The location's 2 character ISO 3166-1 alpha-2 country code. Example: US |
| PostalCode | The location postal code. |
| ExtraNotes | Additional notes about the location. Example: Apartment building, gravel driveway, etc. |
StartDateTime: The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00
EndDateTime: The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00
PickupInstructions: Additional instructions about the pick up request.
DropoffInstructions: Additional instructions about the drop off request.
LanguageCode: The language of the traveler. Will be one of the following options:
en: English
en-us: English (US)
en-gb: English (UK)
fr: French
fr-ca: French (Canadian)
de: German
pt: Portuguese
es: Spanish
nl: Dutch
it: Italian
ja: Japanese
pl: Polish
pt-br: Portuguese (Brazilian)
ru: Russian
hu: Hungarian
ko: Korean
sv: Swedish
zh-cn: Chinese
zh-tw: Traditional Chinese
Currency: The 3-letter ISO 4217 currency code for the reservation amount.
NumPassengers: The number of passengers.
VehicleType: The type of vehicle requested. Will be one of the following options:
100: Sedan
200: Limo
201: Stretch Limo
300: SUV
301: Stretch SUV
400: Van
401: Mini-Bus
402: Bus
500: Motor Coach
501: Antique/Classic
502: Trolley
503: Carriage
600: Shuttle
900: Any
DiscountCode: The discount code information. This parent element contains the following child elements:
post-a-transportation-search - DiscountCode Elements
| Element | Description |
|---|---|
| CorporateID | The user's corporate ID. |
| VendorCode | The user's vendor code. |
| DiscountNumber | The user's discount number. |
Post a transportation search - Airport Elements
AirportCode: The IATA Code for the airport.
Flight: The flight information. This parent element contains the following child elements:
Post a transportation search - Flight Elements
| Element | Description |
|---|---|
| CarrierCode | The airline code. |
| FlightNumber | The flight number. |
| ArrivalDateTime | The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 |
| DepartureDateTime | The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00 |
Post a transportation search - Train Station Elements
| Element | Description |
|---|---|
| StationCode | The station code. |
| StationName | The name of the station. |
| City | The city the station is located in. |
| State | The state the station is located in. Preferably 2 characters, max 10 characters. |
| Train | The train information. This parent element contains the following child elements. |
Post a transportation search - Train Elements
| Element | Description |
|---|---|
| CarrierCode | The code of the train carrier. |
| CarrierName | The name of the train carrier. |
| TrainNumber | The train number. |
| ArrivalDateTime | The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 |
| DepartureDateTime | The train departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00 |
Post a transportation search - Response
The supplier responds to the Limo Search request by returning the details of an available reservation that matches the search criteria.
Content Types
application/xml
Post a transportation search - Content Body
The response will include a CC_LimoSearchReply parent element, with the following child elements:
Error: The error information, if an error occurred. Required. This parent element contains the following child elements:
Post a transportation searh - Error Elements
| Element | Description |
|---|---|
| ErrorCode | The code for the error. Will contain one of the following values: 100: Pickup/dropoff location related error 200: Pickup/dropoff time related error 300: Other request parameters related error 400: Credential related error 500: No rate/service available 900: Unknown error |
| ErrorSource | The source of the error. |
| ErrorDescription | The additional error information. |
RequestData: This parent element contains a copy of the original request data. Only the ServiceType, PickupLocation, DropoffLocation, and StartDateTime elements are required.
Limos: This parent element contains a Limo child element with the available reservation information. Refer to the Limo Elements table for the details of the child elements of the Limo element.
Post a transportation search - Limo Elements
RateInfo: The rate information for the limo. Refer to the Rate Information Elements table for more information. Required.
Vehicle: The type of vehicle. Required. This parent element contains the following child elements:
VehicleType: One of the following values:
100: Sedan
200: Limo
250: Stretch Limo
300: SUV
350: Stretch SUV
400: Van
450: Mini-Bus
500: Motor Coach
600: Shuttle
700: Trolley
800: Carriage
900: Any
Description: The detailed description of the vehicle.
MaxPassengers: The maximum number of passengers allowed in the vehicle. Must be greater than zero.
VehicleID: Information to identify the specific vehicle.
Vendor: The reservation vendor. Required. This parent element contains the following child elements:
Post a transportation search - Vendor Elements
| Element | Description |
|---|---|
| VendorCode | The vendor code for the vendor. |
| VendorName | The vendor's name. |
| PhoneNumber | The vendor's phone number. |
AcceptedFops: The accepted forms of payment. Required. This parent element contains the FormOfPayment child element. The FormOfPayment element contains the allowed forms of payment. The possible child elements are:
Post a transportation search - FormOfPayment Elements
| Element | Description |
|---|---|
| CreditCard | This element will appear if the Credit Card form of payment is accepted. Contains the Type child element with one of the following values: AX - American Express, CA - Master Card, VI - Visa, DS - Discover Card, DC - Diners Club |
| Cash | This element will appear if the Cash form of payment is accepted. |
| Check | This element will appear if the Check form of payment is accepted. |
| DirectBilling | This element will appear if the Direct Billing form of payment is accepted. |
Post a transportation search - Rate Information Elements
| Element | Required? | Description |
|---|---|---|
| RateID | Y | The rate identifier. |
| Rate | Y | The BasePrice + ServiceCharge + SurCharge + Tax |
| RateTypeCode | Y | The code for the rate type. Will be one of the following options: F: Flat rate H: Hourly E: Estimated amount N: Currently not available |
| CategoryCode | N | Extra information that will be passed back during sell request to help identify the rate. |
| Currency | Y | The 3-letter ISO 4217 currency code for the rate amount. |
| NoRateText | N | Explanation of rate type. Provided if RateTypeCode = N |
| MinHours | N | The minimum number of hours for the reservation. |
| DiscountType | N | The type of discount applied. |
| BasePrice | N | The reservation price without taxes, surcharges or service charges. |
| ServiceCharge | N | The service charge for the reservation. |
| SurCharge | N | This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel"> |
| Tax | N | The reservation tax. |
| ExtraPickupCharge | N | Any additional fees for the pickup service. |
| ExtraDropoffCharge | N | Any additional fees for the drop off service. |
| OptionalExtraStopCharge | N | The charge for any additional stops. |
| OptionalExtraTimeCharge | N | The charge for each additional hour. |
Post a transportation search - Examples
XML Example Request
POST /concur/groundtransportation HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoSearchRequest>
<ServiceType>110</ServiceType>
<ClassOfService>100</ClassOfService>
<PickupLocation>
<LocationType>100</LocationType>
<Airport>
<AirportCode />
</Airport>
<Address>209 Madison St., Suite 400</Address>
<City>Alexandria</City>
<State>VA</State>
<Country>US</Country>
<PostalCode>22314</PostalCode>
</PickupLocation>
<DropoffLocation>
<LocationType>200</LocationType>
<Airport>
<AirportCode>DCA</AirportCode>
</Airport>
<Address />
<City />
<State />
<Country />
<PostalCode />
</DropoffLocation>
<StartDateTime>2012-03-14T09:00</StartDateTime>
<EndDateTime />
<PickupInstructions />
<DropoffInstructions />
<LanguageCode>en-us</LanguageCode>
<Currency>USD</Currency>
<NumPassengers>1</NumPassengers>
<DiscountCode />
<VehicleType>100</VehicleType>
</CC_LimoSearchRequest>
XML Example of Successful Response
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoSearchReply size="1396" elaspedMs="782">
<Error>
<ErrorCode />
<ErrorSource />
<ErrorDescription />
</Error>
<RequestData>
<ServiceType>110</ServiceType>
<ClassOfService>100</ClassOfService>
<PickupLocation>
<Airport />
<Address>209 Madison St. #400</Address>
<City>Alexandria</City>
<State>VA</State>
<Country>US</Country>
<PostalCode>22314</PostalCode>
</PickupLocation>
<DropoffLocation>
<Airport>DCA</Airport>
<Address />
<City />
<State />
<Country />
<PostalCode />
</DropoffLocation>
<StartDateTime>2012-02-19T09:00:00</StartDateTime>
<EndDateTime />
<PickupInstructions />
<DropoffInstructions />
<Country>US</Country>
<NumPassengers>1</NumPassengers>
<VehicleType>100</VehicleType>
</RequestData>
<Limos>
<Limo>
<RateInfo>
<RateID>1</RateID>
<Rate>42.50</Rate>
<RateTypeCode>100</RateTypeCode>
<CategoryCode />
<MinHours />
<Currency>USD</Currency>
<NoRateText />
<DiscountType />
<BasePrice>35.00</BasePrice>
<ServiceCharge>5.00</ServiceCharge>
<SurChange desc="fuel">1.00</SurChange>
<Tax>1.50</Tax>
<ExtraPickupCharge />
<ExtraDropoffCharge />
<OptionalExtraStopCharge />
<OptionalExtraTimeCharge />
<Message>Ordinary Limo</Message>
</RateInfo>
<Vehicle>
<VehicleType>Sedan</VehicleType>
<Description>This is a Sedan.</Description>
<MaxPassengers>1</MaxPassengers>
<VehicleID>12</VehicleID>
</Vehicle>
<Vendor>
<VendorCode>LML</VendorCode>
<VendorName>LimoVendor</VendorName>
<PhoneNumber>4354654654</PhoneNumber>
</Vendor>
<AcceptedFops>
<FormOfPayment>
<CreditCard>
<Type>VI</Type>
</CreditCard>
</FormOfPayment>
</AcceptedFops>
</Limo>
</Limos>
</CC_LimoSearchReply>
Update reservation with supplier
This request is sent when the Travel user updates an existing ground transportation reservation.
Update Reservation With Supplier - Request
URI
The Ground Transportation direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:
https://{servername}/concur/groundtransportation
The URI is configured by the supplier when registering the partner application.
Headers
Accept Header
application/xml
Authorization Header
Authentication header with Base64 encoded basic authentication credentials (login ID and password) is required. The basic authentication credentials are established during the application review process.
Authorization: Basic {Base64 encoded LoginID:Password}
Update Reservation With Supplier - Request Body
The request will contain a CC_LimoUpdateRequest parent element, containing the following child elements:
| Element | Required? | Description |
|---|---|---|
| ReservationID | The unique identifier for the reservation. | |
| CorporateClient | The corporate client the booking is on behalf of. This parent element contains a CompanyCode child element containing the code for the company of the client. | |
| Booker | The user booking the reservation. For information about the child elements of this parent element, see the Booker elements table below. | |
| PrimaryPassenger | The passenger contact name for the reservation. For information about the child elements of this parent element, see the PrimaryPassenger elements table below. | |
| ServiceType | The type of service requested. Will contain one of the following values: 100: Point to point 110: One way to airport 111: One way from airport 120: One way to train station 121: One way from train station 200: Hourly 300: Airport to airport |
|
| ClassOfService | The requested service class. Will contain one of the following values: 100: Normal 200: High 300: Highest If this value is not provided by the user, it will default to 100. |
|
| PickupLocation | The pick up location. For information about the child elements of this parent element, see the PickupLocation elements table below. | |
| DropoffLocation | The drop off location. For information about the child elements of this parent element, see the DropoffLocation elements table below. | |
| StartDateTime | The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00 | |
| EndDateTime | The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00 | |
| PickupInstructions | Additional instructions about the pick up request. | |
| DropoffInstructions | Additional instructions about the drop off request. | |
| LanguageCode | The language of the traveler. Will be one of the following options: en: English en-us: English (US) en-gb: English (UK) fr: French fr-ca: French (Canadian) de: German pt: Portuguese es: Spanish nl: Dutch it: Italian ja: Japanese pl: Polish pt-br: Portuguese (Brazilian) ru: Russian hu: Hungarian ko: Korean sv: Swedish zh-cn: Chinese zh-tw: Traditional Chinese |
|
| Currency | The 3-letter ISO 4217 currency code for the reservation amount. | |
| NumPassengers | The number of passengers. | |
| DiscountCode | The discount code information. For information about the child elements of this parent element, see the DiscountCode elements table below. | |
| FormOfPayment | The form of payment for the reservation. For information about the child elements of this parent element, see the FormOfPayment elements table below. | |
| AccountingInfo | The accounting information for the reservation. This parent element contains one or more AccountingField elements: AccountingField1 through AccountingField5. These fields contain detailed accounting information. | |
| RequestedDriver | The name of the requested driver, if available. | |
| SpecialServiceRequest | The details of the special service request, if available. | |
| PickupServiceArrangement | The details of the pickup arrangement, if available. | |
| DropoffServiceArrangement | The details of the dropoff arrangement, if available. | |
| ExtraStopArrangement | The details of the extra stop arrangement, if available. |
Update Reservation With Supplier - Booker Elements
| Element | Description |
|---|---|
| UserID | The user's SAP Concur user ID. |
| EmailAddress | The user's email address. |
| Phone | The user's contact number. |
Update Reservation With Supplier - PrimaryPassenger Elements
| Element | Description |
|---|---|
| FirstName | The contact's first name. |
| LastName | The contact's last name. |
| Phone | The contact's phone number. |
| Phone2 | The contact's backup phone number. |
| CellPhone | The contact's cell phone number. |
| EmailAddress | The contact's email address. |
Update Reservation With Supplier - PickupLocation Elements
| Element | Description |
|---|---|
| LocationType | One of the following: 100 - Address, 200 - Airport, 300 - Train station. |
| Airport | Refer to the Airport elements table. Provided if the LocationType = 200. |
| TrainStation | Refer to the Train Station elements table. Provided if the LocationType = 300. |
| Address | The street address of the location. Provided if the LocationType = 100. |
| City | The location city. |
| State | The location state. Preferably 2 characters, max 10 characters. |
| Country | The location's 2 character ISO 3166-1 alpha-2 country code. Example: US |
| PostalCode | The location postal code. |
| ExtraNotes | Additional notes about the location. Example: Ring doorbell, Holiday Inn, etc. |
Update Reservation With Supplier - DropoffLocation Elements
| Element | Description |
|---|---|
| LocationType | One of the following: 100 - Address, 200 - Airport, 300 - Train station, 400 - As directed. |
| Airport | Refer to the Airport elements table. Provided if the LocationType = 200. |
| TrainStation | Refer to the Train Station elements table. Provided if the LocationType = 300. |
| Address | The street address of the location. Provided if the LocationType = 100. |
| City | The location city. |
| State | The location state. Preferably 2 characters, max 10 characters. |
| Country | The location's 2 character ISO 3166-1 alpha-2 country code. Example: US |
| PostalCode | The location postal code. |
| ExtraNotes | Additional notes about the location. Example: Apartment Building, gravel driveway, etc. |
Update Reservation With Supplier - DiscountCode Elements
| Element Name | Description |
|---|---|
| CorporateID | The user's corporate ID. |
| VendorCode | The user's vendor code. |
| DiscountNumber | The user's discount number. |
FormOfPayment Elements
| Element | Description |
|---|---|
| CreditCard | If present, the passenger will pay with credit card. Refer to the Credit Card Elements table for the child elements. |
| Cash | If present, the passenger will pay cash. |
| Check | If present, the passenger will pay with a check. |
| DirectBilling | If present, the passenger will pay through direct billing. |
Airport Elements
| Element Name | Description |
|---|---|
| AirportCode | The IATA code for the airport. |
| Flight | The flight information. For information about the child elements of this parent element, see the Flight elements table below. |
Flight Elements
| Element Name | Description |
|---|---|
| CarrierCode | The airline code. |
| FlightNumber | The flight number. |
| ArrivalDateTime | The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 |
| DepartureDateTime | The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00 |
Train Station Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| StationCode | The station code. | ||
| StationName | The name of the station. | ||
| City | The city the station is located in. | ||
| State | The state the station is located in. Preferably 2 characters, max 10 characters. | ||
| Train | The train information. For information about the child elements of this parent element, see the Train elements table below. |
Train Elements
| Element Name | Description |
|---|---|
| CarrierCode | The code of the train carrier. |
| CarrierName | The name of the train carrier. |
| TrainNumber | The train number. |
| ArrivalDateTime | The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 |
| DepartureDateTime | The train departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00 |
Update Reservation With Supplier - Credit Card Elements
| Element Name | Description |
|---|---|
| Type | The card type. |
| Number | The card number. |
| Expiration | The card expiration date. Format: 2013-02-19 |
| Name | The name on the card. |
| Address | The street information of the billing address of the car. |
| City | The city of the billing address of the car. |
| State | The state of the billing address of the car. |
| Country | The country of the billing address of the car. |
| PostalCode | The postal code of the billing address of the car. |
Update Reservation With Supplier - Response
The supplier responds to the update request with the reservation details.
Content Types
application/xml
Update Reservation With Supplier - Response Schema
The response will include a CC_LimoUpdateReply parent element, with the following child elements:
| Element | Required? | Description |
|---|---|---|
| Error | Y | The error information, if an error occurred. For information about the child elements of this parent element, see the Error elements table below. |
| ReservationID | N | The identifier for the reservation. |
| Status | N | The status of the reservation. The value will be one of the following: RB: Reservation Booked RA: Reservation Accepted RD: Reservation Declined CB: Change Booked CA: Change Accepted CD: Change Declined XB: Cancellation Requested XA: Cancellation Accepted XD: Cancellation Declined RC: Reservation Closed |
| ConfNum | N | The confirmation number for the reservation. |
| CancelPolicy | N | The cancellation policy for the reservation. |
| CancelNum | N | The cancellation number for the reservation. |
| PrimaryPassenger | Y | The passenger contact name for the reservation. For information about the child elements of this parent element, see the PrimaryPassenger elements table above. |
| ServiceType | Y | The type of service requested. Will contain one of the following values: 100: Point to point 110: One way to airport 111: One way from airport 120: One way to train station 121: One way from train station 200: Hourly 300: Airport to airport |
| ClassOfService | N | The requested service class. Will contain one of the following values: 100: Normal 200: High 300: Highest If this value is not provided by the user, it will default to 100. |
| PickupLocation | Y | The pick up location. For information about the child elements of this parent element, see the PickupLocation elements table above. |
| DropoffLocation | Y | The drop off location. For information about the child elements of this parent element, see the DropoffLocation elements table above. |
| StartDateTime | Y | The time, in GMT, that the reservation must begin. Format: 2015-05-19T18:00:00 |
| EndDateTime | N | The time, in GMT that the reservation will end. Provided for hourly reservations. Format: 2015-05-19T18:00:00 |
| PickupInstructions | N | Additional instructions about the pick up request. |
| DropoffInstructions | N | Additional instructions about the drop off request. |
| LanguageCode | Y | The language of the traveler. Will be one of the following options: en: English en-us: English (US) en-gb: English (UK) fr: French fr-ca: French (Canadian) de: German pt: Portuguese es: Spanish nl: Dutch it: Italian ja: Japanese pl: Polish pt-br: Portuguese (Brazilian) ru: Russian hu: Hungarian ko: Korean sv: Swedish zh-cn: Chinese zh-tw: Traditional Chinese |
| Currency | Y | The 3-letter ISO 4217 currency code for the reservation amount. |
| NumPassengers | N | The number of passengers. |
| RequestedDriver | N | The name of the requested driver, if available. |
| SpecialServiceRequest | N | The details of the special service request, if available. |
| PickupServiceArrangement | N | The details of the pickup arrangement, if available. |
| DropoffServiceArrangement | N | The details of the dropoff arrangement, if available. |
| ExtraStopArrangement | N | The details of the extra stop arrangement, if available. |
| RateInfo | Y | The booked rate details. Refer to the Rate Information elements table below for more information. |
| Vehicle | Y | The vehicle details. For information about the child elements of this parent element, see the Vehicle elements table below. |
| Vendor | Y | The reservation vendor. For information about the child elements of this parent element, see the Vendor elements table below. |
| FormOfPayment | Y | The form of payment for the reservation. For information about the child elements of this parent element, see the FormOfPayment elements table below. |
| RateDisclaimer | N | Disclaimer text about the rate. |
| ProviderFeedback | N | Any additional feedback from the supplier. |
| AccountingInfo | N | The accounting information for the reservation. This parent element contains one or more AccountingField elements: AccountingField1 through AccountingField5. These fields contain detailed accounting information. |
Update Reservation With Supplier - Error Elements
| Element | Description |
|---|---|
| ErrorCode | The code for the error. Will contain one of the following values: 100: Pickup/dropoff location related error 200: Pickup/dropoff time related error 300: Other request parameters related error 400: Credential related error 500: No rate/service available 600: FOP related error 900: Unknown error |
| ErrorSource | The source of the error. |
| ErrorDescription | The additional error information. |
Update Reservation With Supplier - Vehicle Elements
| Element | Description |
|---|---|
| VehicleType | One of the following values: 100: Sedan 200: Limo 250: Stretch Limo 300: SUV 350: Stretch SUV 400: Van 450: Mini-Bus 500: Motor Coach 600: Shuttle 700: Trolley 800: Carriage 900: Any |
| Description | The vehicle description. |
| MaxPassengers | The maximum number of passengers for the car. Must be greater than zero. |
| VehicleID | Information to identify the specific vehicle. |
Update Reservation With Supplier - Rate Information Elements
| Element Name | Required? | Data Type | Description |
|---|---|---|---|
| RateID | Y | The rate identifier. | |
| Rate | Y | The BasePrice + ServiceCharge + SurCharge + Tax | |
| RateTypeCode | Y | The code for the rate type. Will be one of the following options: F: Flat rate H: Hourly E: Estimated amount N: Currently not available |
|
| CategoryCode | N | Extra information that will be passed back during sell request to help identify the rate. | |
| Currency | Y | The 3-letter ISO 4217 currency code for the rate amount. | |
| NoRateText | N | Explanation of rate type. Provided if RateTypeCode = N | |
| MinHours | N | The minimum number of hours for the reservation. | |
| DiscountType | N | The type of discount applied. | |
| BasePrice | N | The reservation price without taxes, surcharges or service charges. | |
| ServiceCharge | N | The service charge for the reservation. | |
| SurCharge | N | This element contains the desc attribute, with text describing the reason for the surcharge. Example: <SurCharge desc="fuel"> |
|
| Tax | N | The reservation tax. | |
| ExtraPickupCharge | N | Any additional fees for the pickup service. | |
| ExtraDropoffCharge | N | Any additional fees for the drop off service. | |
| OptionalExtraStopCharge | N | The charge for any additional stops. | |
| OptionalExtraTimeCharge | N | The charge for each additional hour. |
Update Reservation With Supplier - Vendor Elements
| Element | Description |
|---|---|
| VendorCode | The vendor code for the vendor. |
| VendorName | The vendor's name. |
| PhoneNumber | The vendor's phone number. |
FormOfPayment Elements
| Element | Description |
|---|---|
| CreditCard | If present, the passenger will pay with credit card. Refer to the Reply Credit Card elements table for the child elements. |
| Cash | If present, the passenger will pay cash. |
| Check | If present, the passenger will pay with a check. |
| DirectBilling | If present, the passenger will pay through direct billing. |
Airport Elements
| Element Name | Description |
|---|---|
| AirportCode | The IATA code for the airport. |
| Flight | The flight information. For information about the child elements of this parent element, see the Flight elements table below. |
Flight Elements
| Element Name | Description |
|---|---|
| CarrierCode | The airline code. |
| FlightNumber | The flight number. |
| ArrivalDateTime | The flight arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 |
| DepartureDateTime | The flight departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00 |
Train Station Elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| StationCode | The station code. | ||
| StationName | The name of the station. | ||
| City | The city the station is located in. | ||
| State | The state the station is located in. Preferably 2 characters, max 10 characters. | ||
| Train | The train information. For information about the child elements of this parent element, see the Train elements table below. |
Train Elements
| Element Name | Description |
|---|---|
| CarrierCode | The code of the train carrier. |
| CarrierName | The name of the train carrier. |
| TrainNumber | The train number. |
| ArrivalDateTime | The train arrival time. Only provided for the PickupLocation element. Format: 2015-05-19T18:00:00 |
| DepartureDateTime | The train departure time. Only provided for the DropoffLocation element. Format: 2015-05-19T18:00:00 |
Update Reservation With Supplier - Reply Credit Card Elements
| Element Name | Required? | Description |
|---|---|---|
| Type | The card type. | |
| Number | The card number. | |
| Expiration | The card expiration date. Format: 2013-02-19 |
Examples
XML Example Request
POST /concur/groundtransportation HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoUpdateRequest>
<ReservationID>1234</ReservationID>
<CorporateClient>
<CompanyCode>339</CompanyCode>
</CorporateClient>
<Booker>
<UserID>55414</UserID>
<EmailAddress>cmiller@example.com</EmailAddress>
<Phone>5551234567</Phone>
</Booker>
<PrimaryPassenger>
<FirstName>Chris</FirstName>
<LastName>Miller</LastName>
<Phone>5551234567</Phone>
<Phone2>5551234568</Phone2>
<CellPhone>5551234555</CellPhone>
<EmailAddress>cmiller@example.com</EmailAddress>
</PrimaryPassenger>
<ServiceType>110</ServiceType>
<ClassOfService />
<PickupLocation>
<LocationType>100</LocationType>
<Airport>
<AirportCode />
<Flight>
<CarrierCode />
<FlightNumber />
<ArrivalDateTime />
</Flight>
</Airport>
<TrainStation>
<StationCode />
<StationName />
<City />
<State />
<Train>
<CarrierCode />
<CarrierName />
<TrainNumber />
<ArrivalDateTime />
</Train>
</TrainStation>
<Address>209 Madison St</Address>
<City>Alexandria</City>
<State>VA</State>
<Country>US</Country>
<PostalCode>22314</PostalCode>
<ExtraNotes />
</PickupLocation>
<DropoffLocation>
<LocationType>200</LocationType>
<Airport>
<AirportCode>DCA</AirportCode>
<Flight>
<CarrierCode>UA</CarrierCode>
<FlightNumber>333</FlightNumber>
<DepartureDateTime>2012-02-19T11:29:00</DepartureDateTime>
</Flight>
</Airport>
<TrainStation>
<StationCode />
<StationName />
<City />
<State />
<Train>
<CarrierCode />
<CarrierName />
<TrainNumber />
<DepartureDateTime />
</Train>
</TrainStation>
<Address />
<City />
<State />
<Country />
<PostalCode />
<ExtraNotes />
</DropoffLocation>
<StartDateTime>2012-02-19T09:00:00</StartDateTime>
<EndDateTime />
<PickupInstructions>pick me up</PickupInstructions>
<DropoffInstructions>None</DropoffInstructions>
<LanguageCode>en-us</LanguageCode>
<Currency>USD</Currency>
<NumPassengers>1</NumPassengers>
<DiscountCode>
<CorporateID />
<VendorCode />
<DiscountNumber />
</DiscountCode>
<FormOfPayment>
<Cash />
<Check />
<DirectBilling />
<CreditCard>
<Type>VI</Type>
<Number>XXXXXXXXXXXX1111</Number>
<Expiration>2013-02-19</Expiration>
</CreditCard>
</FormOfPayment>
<AccountingInfo>
<AccountingField1>715</AccountingField1>
<AccountingField2>temp@outtask.com</AccountingField2>
<AccountingField3>11</AccountingField3>
<AccountingField4>Development</AccountingField4>
<AccountingField5/>
</AccountingInfo>
<RequestedDriver />
<SpecialServiceRequest />
<PickupServiceArrangement />
<DropoffServiceArrangement />
<ExtraStopArrangement />
</CC_LimoUpdateRequest>
XML Example of Successful Response
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<CC_LimoUpdateReply>
<Error>
<ErrorCode />
<ErrorSource />
<ErrorDescription />
</Error>
<ReservationID>1234</ReservationID>
<Status>RB</Status>
<ConfNum/>
<CancelPolicy />
<CancelNum/>
<PrimaryPassenger>
<FirstName>Chris</FirstName>
<LastName>Miller</LastName>
<Phone>5551234567</Phone>
<Phone2>5551234568</Phone2>
<CellPhone>5551234555</CellPhone>
<EmailAddress>cmiller@example.com</EmailAddress>
</PrimaryPassenger>
<ServiceType>110</ServiceType>
<ClassOfService />
<PickupLocation>
<LocationType>100</LocationType>
<Airport>
<AirportCode />
<Flight>
<CarrierCode />
<FlightNumber />
<ArrivalDateTime />
</Flight>
</Airport>
<TrainStation>
<StationCode />
<StationName />
<City />
<State />
<Train>
<CarrierCode />
<CarrierName />
<TrainNumber />
</Train>
</TrainStation>
<Address>209 Madison St #400</Address>
<City>Alexandria</City>
<State>VA</State>
<Country>US</Country>
<PostalCode>22314</PostalCode>
<ExtraNotes />
</PickupLocation>
<DropoffLocation>
<LocationType>200</LocationType>
<Airport>
<AirportCode>DCA</AirportCode>
<Flight>
<CarrierCode>UA</CarrierCode>
<FlightNumber>333</FlightNumber>
<DepartureDateTime>2012-02-19T11:29:00</DepartureDateTime>
</Flight>
</Airport>
<TrainStation>
<StationCode />
<StationName />
<City />
<State />
<Train>
<CarrierCode />
<CarrierName />
<TrainNumber />
<DepartureDateTime />
</Train>
</TrainStation>
<Address />
<City />
<State />
<Country />
<PostalCode />
<ExtraNotes />
</DropoffLocation>
<StartDateTime>2012-02-19T09:00:00</StartDateTime>
<EndDateTime />
<PickupInstructions>pick me up</PickupInstructions>
<DropoffInstructions>None</DropoffInstructions>
<LanguageCode>en-us</LanguageCode>
<Currency>USD</Currency>
<NumPassengers>1</NumPassengers>
<RequestedDriver />
<SpecialServiceRequest />
<PickupServiceArrangement />
<DropoffServiceArrangement />
<ExtraStopArrangement />
<RateInfo>
<RateID>5</RateID>
<Rate>42.50</Rate>
<RateTypeCode>E</RateTypeCode>
<CategoryCode />
<MinHours />
<Currency>US</Currency>
<NoRateText />
<DiscountType />
<BasePrice>35.00</BasePrice>
<ServiceCharge>5.00</ServiceCharge>
<SurCharge desc="fuel">1.00</SurCharge>
<Tax>1.50</Tax>
<ExtraPickupCharge />
<ExtraDropoffCharge />
<OptionalExtraStopCharge />
<OptionalExtraTimeCharge />
<Message />
</RateInfo>
<RateDisclaimer />
<Vehicle>
<VehicleType>100</VehicleType>
<Description>This is a Sedan.</Description>
<MaxPassengers>1</MaxPassengers>
<VehicleID>12</VehicleID>
</Vehicle>
<Vendor>
<VendorCode>LML</VendorCode>
<VendorName>LimoVendor</VendorName>
<PhoneNumber>4354654654</PhoneNumber>
</Vendor>
<ProviderFeedback />
<FormOfPayment>
<Cash />
<Check />
<DirectBilling />
<CreditCard>
<Type>VI</Type>
<Number>XXXXXXXXXXXX1111</Number>
<Expiration>2013-02-19</Expiration>
</CreditCard>
</FormOfPayment>
<AccountingInfo>
<AccountingField1>715</AccountingField1>
<AccountingField2>temp@outtask.com</AccountingField2>
<AccountingField3>11</AccountingField3>
<AccountingField4>Development</AccountingField4>
<AccountingField5/>
</AccountingInfo>
</CC_LimoUpdateReply>
Direct Connect - Hotel v2
Introduction
Overview
The Hotel Services v2 Direct Connect provides a method for Travel users to access hotel inventory.
The Hotel Service 2.0 API from SAP Concur is a specification based on OTA 2015 standard for Hotel Suppliers. Please refer to XSD schema of the service and WSDL service description. This Guide provides information how the Hotel Supplier can make their content available for Concur Travel users using Hotel Service 2.0 API. Once the Hotel Supplier has developed and certified their interface with SAP Concur, their inventory will begin appearing in hotel searches by opted-in Travel users. This API has client/server architecture, where SAP Concur acts as client, pulling information from the Hotel Supplier, who acts as server, responding to SAP Concur’s requests. This guide specifies the request and response format required by SAP Concur.
This call-out differs from the in-bound SAP Concur web services in the following ways:
- It uses an out-bound message where SAP Concur calls a public facing API end-point provided by the hotel supplier.
- The supplier configures and maintains the public web service interface. This guide specifies the request and response format required by SAP Concur.
Contents
- Overview
- Product Restrictions
- Supported Operations
- Non-Functional Requirements
- URLs
- Handling of HTML
- Message Structure
Introduction - Product Restrictions
Hotel Service 2 API inventory is not accessible from the SAP Concur mobile app. SAP Concur products are highly configurable, and not all clients will have access to all features.
Supported Operations
- Search
- Availability
- Rate Details
- Hotel Description
- Reservation
- Read-Itinerary
- Cancel
Non-Functional Requirements
Response Times
SAP Concur needs to receive all responses within 55 seconds, otherwise it causes timeout. To prevent no show fees, duplicate bookings and other similar issues, SAP Concur recommends to perform Auto-Cancel by the Hotel Supplier if ReadRQ message is not sent by SAP Concur 5 minutes after HotelResRS message was sent to SAP Concur.
Emergency Technical Contact
The Hotel supplier needs to provide emergency technical contact email that will be used for communication in case of blocking technical issues.
Testing Environment
To allow SAP Concur performing testing, the Hotel Supplier needs to provide testing URL or specify properties for testing in production URL. SAP Concur needs to be able to perform test bookings with testing credit cards.
Introduction - Security
PCI DSS Compliance
As sensitive data and payment card details are transferred via API, the Hotel Suppliers need to comply with PCI DSS standard. SAP Concur is compliant with PCI DSS standard and undergoes regular security audits.
HTTPS
SAP Concur requires TLS 1.2 (Transport Layer Security) SSL protocol for file transfers. The Hotel Supplier will provide SAP Concur HTTPS URL of its end-point. Standard HTTPS port 443 should be used.
URLs
SAP Concur will receive a single URL from the Hotel Supplier. All requests will go to that URL.
For details of all required HTTP headers refer to Headers
SAP Concur is using date as xs:date XML type "2017-05-01".
Handling of HTML
CDATA and HTML code inside of XML nodes and attributes are not allowed. These data will be escaped. The hotel suppliers should not use XML special characters - predefined entities: &, <, >, ", ' inside of ID elements like RatePlanID.
Message Structure
All messages to and from the HS2 API follow this structure:
Requests
- Envelope
- Header
- Body
- OTA_
RQ
Note: The Header element in a request must contain the Authentication element.
Responses
- Envelope
- Header
- Body
- OTA_
RS
Note: The header in the response does not need the Authentication element.
Use Cases
Basic scenario encompassing all the functionality provided by Hotel Service 2 incorporated into Concur Travel starting from a hotel search, through to confirmation of a booking and ending with a cancellation.
Actors
- Primary Actor - Business traveler
- Secondary Actor - Hotel Supplier
Use Case
Business traveler performs a search for hotels given a criteria.
The UI displays the available hotels. The business traveler can then select a hotel with visible rates or request to View Rooms in case they are not present. The Business traveler selects a hotel with rates.
The UI displays all available rates for the chosen hotel. The Business user can see the Cancellation Policy. The business traveler clicks on Hotel Details.
The UI displays the hotel details including a long description. The Business traveler closes the Hotel Details pop-up
The UI displays all available rates for the chosen hotel. The business traveler clicks on Rules and Cancellation Policy.
The UI displays the Rules and the Cancellation Policy for the chosen hotel. The Business Travel closes the Rules and Cancellation Policy pop-up.
The UI displays all available rates for the chosen hotel. The Business traveler selects the top most rate. The Trip Summary page is displayed where the Business traveler can set the Hotel Preferences, Enter Guest information (from their profile), select the method of payment and view the total estimated price. The Business traveler agrees to the hotel's rate rules, restrictions and cancellation policy and clicks Reserve Hotel and Continue.
The UI shows the Trip Details page where the Business traveler can add items to their itinerary and review the current itinerary. The Business traveler clicks Next.
The UI shows the Trip Booking Information page where the Business traveler can add trip details. The Business traveler clicks Next.
The UI shows the Trip Confirmation page where the Business traveler can confirm the booking on cancel it. The Business traveler clicks Confirm Booking.
The UI shows the Finished page where the Business traveler can review the trip overview and see the confirmation number along with the trip locator.
The Business user can view the trip in the Upcoming Trips tab on the main Travel page. The Business traveler clicks on the Trip name.
The UI shows the Trip Overview page. The Business traveler chooses the cancel the hotel reservation, by clicking cancel.
The UI shows the Cancel Trip pop-up where the Business traveler may chooser to enter a comment. The Business traveler clicks OK.
The UI shows the Rules and cancellation policy. The Business traveler accepts the policies by checking the 'I agree ...' button and clicking Continue
The UI shows the trip cancellation page where confirmation and cancellation numbers can be found. The Business traveler closes the pop-up.
Search Criteria
Given the following example:
<RadiusDistance="5" DistanceMax="30" UnitOfMeasureCode="2">
Out of 100 returned hotels in response from the Hotel Supplier first 10 hotels are Most Preferred hotels within the 30km radius. The next 10 hotels are Preferred hotels from 30km radius. The remaining 80 hotels are hotels with no preference within the 5km radius. Note: The preference level is defined by the HotelPreference element in the TPA_Extensions, which is outlined in Search.
Reservation and Read Requests
SAP Concur will follow up a Reservation Request with a Read request as soon as possible after processing the Reservation Response. If a Read request does not arrive within 5 minutes for a given Reservation, then the supplier should treat that Reservation as an orphan and should thus seek to cancel it.
General System Overview

HTTP Headers
SAP Concur will send the user-name and password in both the HTTP header and the SOAP header. If the username and password generates an authentication error, then SAP Concur expects an HTTP 403 response.
HTTP Headers
SAP Concur will send the following HTTP headers in every request. The contents of the Authentication header will be repeated in the SOAP payload. Please note that some libraries used to handle the requests may be case sensitive.
| Name | Type | Description |
|---|---|---|
Authorization |
string |
A Base64 encoded string in the form of Basic <username:password>. |
SOAPAction |
string |
The message type. The action will always be sent in lowercase. Example: search |
Content-Type |
string |
All communication with the HS2 API is by way of a application/xml content type. |
Accept |
string |
SAP Concur will always set the Accept header to application/xml. |
Accept-Charset |
string |
SAP Concur will always set the Accept-Charset header to utf-8. |
concur-correlationid |
string |
This unique code can be used during troubleshooting as it identifies the API call in the log files. |
concur-traveleruuid |
string |
UUID that identifies the traveler within concur. Only sent when available. |
concur-loginid |
string |
Login ID of traveler within concur. Only sent when available. |
Supported Soapactions:
| Soapaction | Functionality |
|---|---|
search |
Used to perform Search |
availability |
Used to perform Availability |
detail |
Used to perform Hotel Description |
book |
Used to perform Reservation |
read |
Used to perform Read Itinerary |
cancel |
Used to perform Cancel |
HTTP Headers - Troubleshooting
In order to assist with troubleshooting, SAP Concur provides a unique correlationId in the request header. The key to look for is correlationid. This unique code can be used during troubleshooting as it identifies the API call in the log files. You should record this information in your own API call logs as well so that you can pass this information on to the SAP Concur support team.
Example HTTP Header from network capture:
Accept: application/xml
Accept-Charset: utf-8
Authorization: *******************
concur-correlationid: A75CE5BC-90BA-4BF8-8DEA-69FA2E66E936
concur-loginid: abc@concur.com
concur-traveleruuid: <valid uuid>
Content-Type: application/xml; charset="utf-8"
SOAPAction: search
Accept-Encoding: gzip
Soap Header
The Soap header nested in the Envelope will contain an authentication element.
authentication
| Name | Type | Description |
|---|---|---|
userid |
string |
Required Contains the authentication details. |
password |
string |
Required Contains the authentication details. |
Sample:
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>testLogin123</userid>
<password>xxxxxxxxxxxx</password>
</authentication>
</Header>
Login and password are provided by the Hotel supplier for SAP Concur as API consumer, not per customer.
OTA Message Headers
Every message must contain the following required attributes and elements. On top of these each message may specify extra attributes and elements. Refer to a specific messages' page for details.
Request Message Headers
| Name | Type | Description |
|---|---|---|
EchoToken |
stringLength1to128 |
Required A reference for additional message identification, assigned by the requesting host system. |
Version |
double |
Required The OpenTravel message version indicated by a decimal value. |
PrimaryLangID |
string |
Required The primary language preference for the message encoded as ISO 639-1. |
AltLangID |
string |
Required The alternate language for a customer or message encoded as ISO 639-1. |
POS |
complex |
Required Point of Sale (POS) identifies the party or connection channel making the request. |
POS
| Name | Type | Description |
|---|---|---|
Sources |
complex |
Required This holds the details about the requestor. Max Occurrence: 10 |
Source
SAP Concur will always send the ISO Currency.
| Name | Type | Description |
|---|---|---|
ISOCurrency |
alphaLength3 |
Required Currency code. |
RequestorID |
complex |
An identifier of the entity making the request Examples: ATA/IATA/ID number, Electronic Reservation Service Provider (ERSP), Association of British Travel Agents (ABTA) |
RequestorID
| Name | Type | Description |
|---|---|---|
Type |
stringLength1to32 |
Required Supported value: 1 |
ID |
stringLength1to32 |
Required The requestor ID. |
Response Message Headers
The supplier is required to respond with the following attributes and elements in the root of any message. Each message may specify extra attributes and elements. Refer to a specific messages' page for details.
| Name | Type | Description |
|---|---|---|
EchoToken |
stringLength1to128 |
Required A reference for additional message identification, assigned by the requesting host system. When a request message includes an echo token the corresponding response message MUST include an echo token with an identical value. |
Timestamp |
datetime |
Required Timestamp of the response operation. |
Version |
double |
Required The OpenTravel message version indicated by a decimal value. |
PrimaryLangID |
string |
Required The primary language preference for the message encoded as ISO 639-1. |
AltLangID |
string |
Required The alternate language for a customer or message encoded as ISO 639-1. |
Success / Error |
complex |
Required Indicates Success Or Error. Refer to the Error Handling page for more details. |
Error Handling
SAP Concur is able to handle HTTP errors, but the preference is for the supplier to return an OTA error whenever possible. SAP Concur only ever expects one OTA error per message. Any extra errors will be ignored. Currently OTA Warnings are not supported and will be ignored.
If the error is specifically related to application level errors, please do not respond with any other error types (HTTP etc.). If you have server level issues, then it is OK to respond with HTTP standard error codes.
Errors should always be returned in a response. For example:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_HotelSearchRS xmlns="http://www.opentravel.org/OTA/2003/05"
AltLangID="en"
EchoToken="11111111-2222-3333-4444-555555555555" PrimaryLangID="en"
Version="4">
<Errors>
<Error Code="322" ShortText="No availability" Type="13"></Error>
</Errors>
</OTA_HotelSearchRS>
</soap:Body>
</soap:Envelope>
If an error is present in any message, then the content of that message is discarded and only the error element is processed. Any text from the supplier will be logged and a SAP Concur message will be displayed to the user.
Currently SAP Concur does not support displaying of supplier generated errors directly in the UI.
SAP Concur only uses the very first error that is returned, therefore any excess error elements are dropped. Any errors without a Type attribute will automatically be treated as 1 meaning Unknown. See the Error Types table below.
| Name | Type | Description |
|---|---|---|
Errors |
complex |
Element used to hold error elements. SAP Concur only expects one (1) error element. An empty errors element will be treated as an Unknown error. |
Errors
| Name | Type | Description |
|---|---|---|
Error |
complex |
Element to describe a particular error. Extra text can be placed inside this element, however SAP Concur expects the error message to be sent in the ShortText attribute. |
Error
| Name | Type | Description |
|---|---|---|
Type |
string |
An error type code. See the Error Types below. |
ShortText |
string |
Required A description of the error. The content of this attribute will be logged, but never displayed to the user. |
Code |
string |
Required An error code for a specific error. |
Error Types
SAP Concur supports the following Error Type Codes in any of the responses:
| Code | Name | Description |
|---|---|---|
| 1 | Unknown |
Indicates an unknown error. |
| 2 | No implementation |
Indicates that the target business system has no implementation for the intended request. |
| 13 | Application error |
Indicates that an involved back-end application returned an error which is passed back in the response message. |
Note: The OTA Error-Type code of 4 - Authentication (indicates the message lacks adequate security credentials) is not expected by SAP Concur. For all authentication errors SAP Concur expects an HTTP 403.
SAP Concur expects the following errors under the given error types:
Error Type Code 1: Unknown
| Error Code | Description | Example |
|---|---|---|
| 188 | Transaction error | For errors not specified in other codes. Internal supplier log ID can be provided in ShortText for debugging. |
Error Type Code 2: No Implementation
| Error Code | Description | Example |
|---|---|---|
| 1 | Not implemented | The supplier can respond with this error if the end point called is not yet implemented. |
Error Type Code 13: Application Error
| Error Code | Description | Example |
|---|---|---|
| 242 | Credit card number is invalid or missing | Missing credit card number. |
| 320 | Invalid value | Comma separated node or attribute and sent value should be provided in the content of the error element. Example: <Error Code="320" ShortText="Invalid value" Type="13">StayDateRange:2019-11-33</Error> |
| 322 | No availability | Hotel Codes should be provided in content of the element. Example: <Error Code="322" ShortText="No availability" Type="13">HTL4444,HTL5555</Error> |
| 424 | No hotels found which match this input | Search parameters - geo-code and radius should be provided in content of the element and formatted as tokenized list: Latitude, Longitude, Radius, Unit of Measure code. Example: <Error Code="322" ShortText="No availability" Type="13">50.111,40.222,5,2</Error> |
| 95 | Booking already cancelled | Booking already cancelled. |
| 438 | Requested rate not available | List of comma separated RatePlanID's should be provided in content of the element. Example: <Error Code="322" ShortText="No availability" Type="13">111,222</Error> |
| 748 | Invalid corporate ID | Requestor ID should be provided in the content of the element. |
| 400 | Invalid property code | List of comma separated hotel codes should be provided in content of the element. Example: <Error Code="322" ShortText="No availability" Type="13">HTL4444,HTL5555</Error> |
| 385 | Invalid confirmation or cancellation number | Reservation ID should be provided in content of the element. |
Search
Message to perform the initial search for hotels.
| SOAPAction | OTA Name | Message Structure |
|---|---|---|
| search | HotelSearch | OTA_HotelSearchRQ |
Search - Request
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>user</userid>
<password>password</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_HotelSearchRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="4"
PrimaryLangID="de" AltLangID="de" MaxResponses="100">
<POS>
<Source ISOCurrency="USD">
<RequestorID Type="1" ID="47777"></RequestorID>
</Source>
</POS>
<Criteria>
<Criterion>
<Position Latitude="52.520007" Longitude="13.404954"></Position>
<RefPoint></RefPoint>
<HotelRef HotelName="sunshine"></HotelRef>
<Radius Distance="5" DistanceMax="30" UnitOfMeasureCode="1"></Radius>
<StayDateRange Start="2018-09-26" End="2018-09-27"></StayDateRange>
</Criterion>
</Criteria>
<TPA_Extensions>
<CustomFields>
<CustomField Name="OrgUnit" Value="Travel Agents"></CustomField>
</CustomFields>
</TPA_Extensions>
</OTA_HotelSearchRQ>
</Body>
</Envelope>
OTA_HotelSearchRQ
| Name | Type | Description |
|---|---|---|
MaxResponses |
integer |
Required SAP Concur currently supports 100 search results in one (1) message. If more than 100 results are returned SAP Concur drops all results after the 100th entry. |
Criteria |
complex |
Required Specified hotel search criteria. |
TPA_Extensions |
complex |
This adds an Org Unit name to the Search request. |
Criteria
| Name | Type | Description |
|---|---|---|
Criterion |
complex |
Required Child elements that identify a single search criterion by criteria type. |
Criterion
The criterion is used to define the search criteria. Currently we support only one Criterion.
| Name | Type | Description |
|---|---|---|
Position |
complex |
Required for Search request only, but optional for Availability request. Used to specify the geographic coordinates of a location, expressed in notation specified by ISO standard 6709. |
HotelRef |
complex |
Indicates the detail of hotel reference information. |
RefPoint |
stringLength0to64 |
The reference point element allows for a search by proximity to a designated reference point by name. |
Radius |
complex |
Used to specify the extent of a search area. The extent is relative to an element (position, address, hotelRef, etc.) present in this ItemSearchCriterionType that specifies a location. |
StayDateRange |
complex |
Required Range of dates using ISO 8601. |
TPA_Extensions
| Name | Type | Description |
|---|---|---|
CustomFields |
complex |
This adds Org Unit name. |
Search - CustomFields
| Name | Type | Description |
|---|---|---|
CustomField |
- | - |
Name |
xs:string |
- |
Value |
xs:string |
- |
Position
| Name | Type | Description |
|---|---|---|
Latitude |
stringLength1to16 |
Required The measure of the angular distance on a meridian north or south of the equator. |
Longitude |
stringLength1to16 |
Required The measure of the angular distance on a meridian east or west of the prime meridian. |
HotelRef
| Name | Type | Description |
|---|---|---|
HotelName |
stringLength1to128 |
A text field used to communicate the proper name of the hotel. |
Radius
The radius element is used along with the Hotel Preference to categorize the search results.
| Name | Type | Description |
|---|---|---|
Distance |
stringLength1to16 |
Required The distance from a reference point. |
DistanceMax |
stringLength1to16 |
Attribute indicating the distance from a reference point or Preferred (Corporate) hotels. |
UnitOfMeasureCode |
stringLength1to16 |
Required The unit of measure in a code format. Refer to OpenTravel Code List of Measure Code (UOM). SAP uses 1 for miles, 2 for kilometers. |
StayDateRange
| Name | Type | Description |
|---|---|---|
Start |
date, time, or datetime |
Required The starting value of the time span. |
End |
date, time, or datetime |
Required The ending value of the time span. |
Search - Response
The maximum allowed size of OTA_HotelSearchRS is 1 MB. Any response that exceeds this limit will be dropped.
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_HotelSearchRS xmlns="http://www.opentravel.org/OTA/2003/05" AltLangID="EN" PrimaryLangID="EN" Version="4">
<Success/>
<Properties>
<Property ChainCode="AB" ChainName="1111" HotelCode="22222" HotelName="Sunshine Hotel">
<Position Latitude="52.4567" Longitude="13.5635"/>
<Address>
<AddressLine>An der Wuhlheide</AddressLine>
<CityName>Berlin</CityName>
<PostalCode>10115</PostalCode>
<CountryName Code="DE">Federal Republic of Germany</CountryName>
</Address>
<ContactNumbers>
<ContactNumber CountryAccessCode="49" PhoneNumber="56940033" PhoneTechType="1"/>
</ContactNumbers>
<Award Rating="4"/>
<HotelAmenity Code="68"/>
<TPA_Extensions>
<HotelPreference>not_preferred</HotelPreference>
<TPA_HotelPreviewImageURI>
<URL>url_to_the_picture.jpg</URL>
</TPA_HotelPreviewImageURI>
</TPA_Extensions>
</Property>
</Properties>
<TPA_Extensions>
<SearchSessionToken>5EA6C45E55104704E4</SearchSessionToken>
</TPA_Extensions>
</OTA_HotelSearchRS>
</soap:Body>
</soap:Envelope>
OTA_HotelSearchRS
| Name | Type | Description |
|---|---|---|
Properties |
complex |
Required A collection of individual property information. |
TPA_Extensions/SearchSessionToken |
stringLength1to128 |
Optional A token that links the Search results to Availability and Reservation requests. |
Properties
| Name | Type | Description |
|---|---|---|
Property |
complex |
Required A property that matches some or all of the search criteria. |
Property
| Name | Type | Description |
|---|---|---|
ChainCode |
stringLength1to32 |
2-letter valid GDS chain code. The code that identifies a hotel chain or management group. Must be present to support filtering, preferences or travel rules base on chains |
ChainName |
stringLength1to32 |
The name of the hotel chain. Examples: Hilton, Marriott, Hyatt, Starwood |
HotelCode |
stringLength1to32 |
Required The code that uniquely identifies a single hotel property. Used in other OTA messages. |
HotelName |
stringLength1to32 |
Required A text field used to communicate the proper name of the hotel. |
Position |
complex |
Required Refer to Position in the Request. |
Address |
complex |
Required Public address of the hotel property. |
ContactNumbers |
complex |
Contact numbers. |
Award |
complex |
An element that identifies the hotel ratings. |
HotelAmenity |
complex |
List of hotel amenities. |
TPA_Extensions |
complex |
SAP Concur-specific extension of OTA spec. This adds support for extra property fields. |
Search - Address
| Name | Type | Description |
|---|---|---|
AddressLine |
stringLength1to255 |
The screenname and number. Maximum occurrences: 5 |
CityName |
stringLength1to64 |
Name of the city. |
PostalCode |
stringLength1to16 |
The postal code. |
StateProv |
complex |
Name of the state. |
CountryName |
complex |
Country name. Example: Ireland |
StateProv
| Name | Type | Description |
|---|---|---|
StateCode |
stringLength0to64 |
The standard code or abbreviation for the state, province, or region (note the code may not be available for all states). |
CountryName
| Name | Type | Description |
|---|---|---|
Code |
stringLength0to64 |
Required The name or ISO 3166 code of a country. |
ContactNumbers
| Name | Type | Description |
|---|---|---|
ContactNumber |
`complex | Element which contains the ContactNumber. SAP Concur only accepts one (first) ContactNumber of each supported type. |
ContactNumber
| Name | Type | Description |
|---|---|---|
CountryAccessCode |
stringLength1to32 |
The country code. |
PhoneNumber |
stringLength1to32 |
Required The phone number. |
PhoneTechType |
string |
SAP Concur currently only supports a PhoneTechType set to 1 (phone) or 3 (fax). You can omit this field only in case you are providing one contact number. We suggest to fill the type in all cases, it may become mandatory in the future. |
Award
| Name | Type | Description |
|---|---|---|
Rating |
integer |
Required Hotel rating should be an integer number from 0 to 5, representing its star rating. |
HotelAmenity
| Name | Type | Description |
|---|---|---|
Code |
string |
Required Refer to OpenTravel Code List Hotel Amenity Code (HAC). |
TPA Extensions
| Name | Type | Description |
|---|---|---|
HotelPreference |
stringLength1to32 |
Required SAP Concur allows customers to override property preference in the system settings. Supported values: not_preferred, less_preferred, preferred, most_preferred |
TPA_HotelPreviewImageURI |
complex |
Required Details for an image of a given category. |
TPA_HotelPreviewImageURI
| Name | Type | Description |
|---|---|---|
URL |
stringLength1to32 |
Required URL of the multimedia item for a specific format. SAP Concur supports one image URL in the Search Response. For the ability to display more images refer to Descriptive Info message. The image will be used as a thumbnail and should be limited to 70x70 pixels to prevent image artifacts by scaling. |
Availability
Message to retrieved the availability of hotels.
| SOAPAction | OTA Name | Message Structure |
|---|---|---|
| availability | HotelAvail | OTA_HotelAvailRQ |
- Request
- Response
- Schema
- Room Stays
- Room Stay
- Room Types
- Room Type
- Room Descriptions
- Rate Plans
- Rate Plan
- Rate Plan Description
- Guarantee
- Supported Guarantee Types
- Supported Guarantee Required
- Deadline
- Cancel Penalties
- Cancel Penalty
- Meals Included
- Rooms Rates
- Room Rate
- Rates
- Rate
- Payment Policies
- Guarantee Payment
- Accepted Payments
- Accepted Payment
- Payment Card
- Card Type
- Total
- Rate Descriptions
- TPA Extensions
- Timespan
- Basic Property Info
- Relationship Between RoomID and RatePlanID
Availability Request
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>user</userid>
<password>password</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_HotelAvailRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="5"
PrimaryLangID="de" AltLangID="de">
<POS>
<Source ISOCurrency="USD">
<RequestorID Type="1" ID="1234567"></RequestorID>
</Source>
</POS>
<AvailRequestSegments>
<AvailRequestSegment>
<HotelSearchCriteria>
<Criterion>
<HotelRef ChainCode="ZZ" HotelCode="111222"></HotelRef>
</Criterion>
</HotelSearchCriteria>
<StayDateRange Start="2018-10-26" End="2018-10-28"></StayDateRange>
<RoomStayCandidates>
<RoomStayCandidate>
<GuestCounts>
<GuestCount AgeQualifyingCode="10" Count="1"></GuestCount>
</GuestCounts>
</RoomStayCandidate>
</RoomStayCandidates>
<TPA_Extensions>
<SearchSessionToken>5EA6C45E55104704E4</SearchSessionToken>
</TPA_Extensions>
</AvailRequestSegment>
</AvailRequestSegments>
</OTA_HotelAvailRQ>
</Body>
</Envelope>
Availability Schema
OTA_HotelAvailRQ
| Name | Type | Description |
|---|---|---|
AvailRequestSegments |
complex |
Required A collection of AvailRequestSegment. Each segment includes a collection of criteria that requests a bookable entity, which may include designated rate plans, room types, amenities or services. The request can be used for guest rooms or other inventory items for which availability is sought. Each segment will be presumed to have a unique date range for each request. SAP Concur will only ever send one AvailRequestSegments. |
AvailRequestSegments
| Name | Type | Description |
|---|---|---|
AvailRequestSegment |
complex |
Required To accommodate the ability to perform multiple requests within one message, the availability request contains the repeating element, AvailRequestSegment. Each segment includes a collection of criteria that requests a bookable entity, which may include designated rate plans, room types, amenities or services. The request can be used for guest rooms or other inventory items for which availability is sought. Each segment will be presumed to have a unique date range for each request. SAP Concur will only ever send one AvailRequestSegment. |
AvailRequestSegment
| Name | Type | Description |
|---|---|---|
HotelSearchCriteria |
complex |
Required Specified hotel search criteria. SAP Concur will send only one (1) HotelSearchCriteria. |
StayDateRange |
complex |
Range of dates using ISO 8601. |
TPA_Extensions/SearchSessionToken |
stringLength1to128 |
The token obtained from Search response that links the Search results to Availability and [Reservation]#reservation) requests. |
HotelSearchCriteria
| Name | Type | Description |
|---|---|---|
Criterion |
complex |
Required Refer to Criterion in Search. Note that for Availability the Criterion will only have the HotelRef element. Other elements will not be sent. HotelSearchCriteria can contain multiple Criterion elements. Each will have a unique HotelCode per Availability request. |
Availability - Criterion
| Name | Type | Description |
|---|---|---|
HotelRef/HotelCode |
stringLength1to16 |
The code that uniquely identifies a single hotel property. The hotel code is decided by vendors. |
HotelRef/ChainCode |
stringLength1to8 |
The code that identifies a hotel chain or management group. The hotel chain code is decided between vendors. This attribute is optional if the hotel is an independent property that can be identified by the HotelCode attribute. |
Availability - StayDateRange
| Name | Type | Description |
|---|---|---|
Start |
date, or time, or datetime |
Required The starting value of the time span. |
End |
date, or time, or datetime |
Required The ending value of the time span. |
RoomStayCandidates
| Name | Type | Description |
|---|---|---|
RoomStayCandidate |
complex |
Required Element used to identify available room products. |
RoomStayCandidate
| Name | Type | Description |
|---|---|---|
GuestCounts |
complex |
Required A collection of guest counts associated with room stay. |
GuestCounts
| Name | Type | Description |
|---|---|---|
GuestCount |
complex |
Required A recurring element that identifies the number of guests and ages of the guests. It currently contains hardcoded values only. See GuestCount below. |
GuestCount
| Name | Type | Description |
|---|---|---|
Count |
integer |
Required SAP Concur only supports one guest. Supported values: 1 |
AgeQualifyingCode |
integer |
Required Supported values: 10 |
Availability Response
The maximum allowed size of OTA_HotelAvailRS is 5 MB. Any response that exceeds this limit shall be dropped.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_HotelAvailRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="5">
<Success/>
<RoomStays>
<RoomStay>
<RoomTypes>
<RoomType RoomID="1">
<RoomDescription>
<Text>Test room description.</Text>
</RoomDescription>
</RoomType>
</RoomTypes>
<RatePlans>
<RatePlan RatePlanID="XNFYP4I" AvailabilityStatus="ChangeDuringStay">
<Guarantee>
<Deadline AbsoluteDeadline="2017-01-26T18:00:00"/>
</Guarantee>
<CancelPenalties>
<CancelPenalty>
<Deadline AbsoluteDeadline="2017-01-26T18:00:00"/>
<PenaltyDescription>
<Text>REFUNDABLE</Text>
<Text>test cancel description</Text>
</PenaltyDescription>
</CancelPenalty>
</CancelPenalties>
<MealsIncluded Breakfast="true"/>
<RatePlanDescription>
<Text>Test rate plan description.</Text>
</RatePlanDescription>
</RatePlan>
</RatePlans>
<RoomRates>
<RoomRate RoomID="1" RatePlanID="XNFYP4I">
<Rates>
<Rate RateTimeUnit="FullDuration">
<PaymentPolicies>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="VI"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
</PaymentPolicies>
<Total AmountAfterTax="348.00" AmountBeforeTax="248.00" CurrencyCode="EUR" DecimalPlaces="2"/>
<RateDescription>
<Text>Test rate description. Both before and after tax.</Text>
</RateDescription>
<TPA_Extensions>
<RequireSeriesCode>true</RequireSeriesCode>
</TPA_Extensions>
</Rate>
</Rates>
</RoomRate>
</RoomRates>
<TimeSpan End="2018-10-28" Start="2018-10-26"/>
<BasicPropertyInfo ChainCode="ZZ" HotelCode="419430"/>
</RoomStay>
</RoomStays>
<TPA_Extensions RateDetailsInd="false"></TPA_Extensions>
</OTA_HotelAvailRS>
</soap:Body>
</soap:Envelope>
Schema
OTA_HotelAvailRS
| Name | Type | Description |
|---|---|---|
RoomStays |
complex |
Required A collection of details on the room stay including time span of this room stay, and financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties. |
TPA_Extensions/RateDetailsInd |
boolean |
If true or omitted, ratedetails will not be called to retrieve the cancellation policy and rate change details; if false, ratedetails will be called. |
RoomStays
| Name | Type | Description |
|---|---|---|
RoomStay |
complex |
Required Details on the room stay including time span of this room stay, and financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties. A room stay represents one (1) hotel. |
RoomStay
For a description of the relationship between the RoomID and RatePlanID refer to "Relationship between RoomID and RatePlanID".
| Name | Type | Description |
|---|---|---|
RoomTypes |
complex |
Required Details on the room stay including guest counts, time span of this room stay, pointers to res guests, guest memberships, comments, and special requests pertaining to this particular room stay. Financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties. |
RatePlans |
complex |
Required A collection of rate plans associated with a particular room stay. The rate plan element is used to contain all the rate information for a single rate plan Code (example: RACK) for a given date range. A given rate plan may have variable rates, over the effective period of the rate plan, this is represented by the child element rates. |
RoomRates |
complex |
Required List of room rates. |
TimeSpan |
datetimespan |
Required The time span which covers the room stay. The attributes of the OTA DateTimeSpan data type are based on the W3C base data types of timeInstant and timeDuration using ISO 8601. |
BasicPropertyInfo |
complex |
Property Information for the room stay. |
RoomTypes
| Name | Type | Description |
|---|---|---|
RoomType |
complex |
Required Provides details regarding rooms, usually guest rooms. The room description text will be used for each room (defined as a RoomRate) which specifies the same RoomID. |
RoomType
| Name | Type | Description |
|---|---|---|
RoomID |
stringLength1to16 |
Required A string value representing the unique identification of a room if the request is looking for a specific room type. |
RoomDescription |
complex |
Textual information regarding the room. |
RoomDescription
| Name | Type | Description |
|---|---|---|
Text |
stringLength1to32 |
Required Only one (1) text element is supported. If multiple text elements are specified, the last one is used and all others are dropped. All text passed is HTML encoded. |
RatePlans
| Name | Type | Description |
|---|---|---|
RatePlan |
complex |
Required Defines the details of the rate plan as used in the booking process. Policies and descriptions that apply to a rate plan. Information significant to defining a rate plan. |
RatePlan
| Name | Type | Description |
|---|---|---|
RatePlanID |
stringLength1to64 |
Required A text field used to indicate a special ID code that is associated with the rate and is essential in the reservation request in order to obtain the rate. Examples: Corporate ID. |
AvailabilityStatus |
stringLength1to32 |
Required Used to specify an availability status for the rate plan. Supported values: AvailableForSale, ChangeDuringStay. |
Guarantee |
complex |
Required Guarantee information that applies to the rate plan. SAP Concur only expects one (1) Guarantee element per RatePlan. |
CancelPenalties |
complex |
Required if RateDetailsInd is true or not present Collection of cancellation penalties. If the cancel penalties are not provided SAP Concur will display: "Cancellation policy not provided by vendor". |
MealsIncluded |
complex |
Required if RateDetailsInd is true or not present Defines which meals are included with this rate program. |
RatePlanDescription |
complex |
Textual information regarding the Rate Plan. |
RatePlanDescription
| Name | Type | Description |
|---|---|---|
Text |
stringLength1to32 |
Required Only one (1) text element is supported. If multiple text elements are specified, the last one is used and all others are dropped. All text passed is HTML encoded. |
Guarantee
| Name | Type | Description |
|---|---|---|
GuaranteeType |
string |
Required The guarantee information to hold a reservation. |
Deadline |
complex |
Required Guarantee deadline, absolute or relative. |
Supported GuaranteeTypes
| GuaranteeType | Description |
|---|---|
Deposit |
In SAP Concur this value is seen as RequiredDeposit. |
DepositRequired |
In SAP Concur this value is seen as RequiredDeposit. |
CC/DC/Voucher |
In SAP Concur this value is seen as RequiredGuarantee. |
PrePay |
In SAP Concur this value is seen as RequiredPrepay. |
None |
In SAP Concur this value is seen as Never. No guarantee is required if user books a room with this type. |
GuaranteeRequired |
RequiredGuarantee. If the Guarantee type cannot be mapped to any accepted type, it will be set to RequiredGuarantee. This value is the default. |
Supported GuaranteeRequired
| GuaranteeRequired | Description |
|---|---|
always |
Guarantee is required all the time independently on deposit account setting. |
never |
Guarantee is never required. |
default |
Guarantee is required if no deposit account is set up. |
Deadline
| Name | Type | Description |
|---|---|---|
AbsoluteDeadline |
time or datetime |
Required Defines the absolute deadline. Either this or the offset attributes may be used. |
CancelPenalties
| Name | Type | Description |
|---|---|---|
CancelPenalty |
complex |
Required Defines the cancellation penalty of the hotel facility. |
CancelPenalty
| Name | Type | Description |
|---|---|---|
PenaltyDescription |
complex |
Text description of the penalty in a given language. This element may contain a maximum of 9 children text fields. Any excess text elements are dropped. |
Deadline |
complex |
Required Cancellation deadline, absolute or relative. See Deadline above. |
PenaltyDescription
| Name | Type | Description |
|---|---|---|
Text |
formattedText |
Required Formatted text content in a given language. All text passed is HTML encoded. |
MealsIncluded
| Name | Type | Description |
|---|---|---|
Breakfast |
boolean |
Required If true, indicates breakfast is included. If false, indicates it is excluded. In both cases this information is shown to a customer in the rate description. |
RoomRates
| Name | Type | Description |
|---|---|---|
RoomRate |
complex |
Required Contains the rate details. |
RoomRate
| Name | Type | Description |
|---|---|---|
RoomID |
complex |
Required Room Type ID. The combination of RoomID and RatePlanID must be unique for a RoomStay. |
RatePlanID |
complex |
Required Rate plan ID for which this rate is applicable for. |
Rates |
complex |
Required Contains the rate for the given room. SAP Concur only expects one (1) rate inside the Rates element. Refer to Rate Details for rate change details. |
Rates
| Name | Type | Description |
|---|---|---|
Rate |
complex |
Required Contains the rate for the given room. Only one (1) Rate element is expected. Refer to Rate Details for rate change details. |
Rate
| Name | Type | Description |
|---|---|---|
RateTimeUnit |
string |
Indicates the time unit for the rate. Supported values: FullDuration, Day. Default: FullDuration |
PaymentPolicies |
complex |
Payment policies for this rate. |
Total |
complex |
Required A description of the rate. |
RateDescription |
complex |
A textual description of a rate. Only one (1) Rate Description element is expected. |
TPA_extensions |
complex |
TPA extensions for a rate. |
PaymentPolicies
| Name | Type | Description |
|---|---|---|
GuaranteePayment |
complex |
Element containing the guarantee payment type. |
GuaranteePayment
| Name | Type | Description |
|---|---|---|
AcceptedPayments |
complex |
Required If used, at least one (1) AcceptedPayment should be present. |
AcceptedPayments
| Name | Type | Description |
|---|---|---|
AcceptedPayment |
complex |
Required Accepted payment type. |
AcceptedPayment
| Name | Type | Description |
|---|---|---|
PaymentCard |
complex |
Required Description of payment type. |
PaymentCard
| Name | Type | Description |
|---|---|---|
CardType |
complex |
Required String representation of a card type. Allowed values: AmericanExpress, BankOfAmerica, BritishAirways, CapitalOne, Chase, Citibank, ContinentalAirlines, DeltaAirlines, DiscoverCard, Disney, Eurocard, Hilton, Hyatt, Mariott, Mastercard, RitzCarlton, SouthwestAirlines, StarwoodHotels, UnitedAirlines, USAirways, VISA, Other_. See Code and Description if card type is other_. |
CardType
| Name | Type | Description |
|---|---|---|
Code |
string |
If CardType is Other_, use this attribute for card code. Examples: AX, VI. |
Description |
string |
If CardType is Other_, use this attribute for card description. |
Total
| Name | Type | Description |
|---|---|---|
AmountBeforeTax |
string |
Required The total amount not including any associated tax. Examples: sales tax, VAT, GST |
AmountAfterTax |
string |
Required The total amount including all associated taxes. Examples: sales tax, VAT, GST |
CurrencyCode |
alphaLength3 |
Required Currency code. |
DecimalPlaces |
integer |
Decimal places for currency code. This is an ISO 4217 standard "minor unit" for the number of decimal places for a particular currency. |
RateDescription
| Name | Type | Description |
|---|---|---|
Text |
stringLength1to32 |
Required SAP Concur only expects one (1) text field for the rate description. Any excess text elements will be ignored. All text passed is HTML encoded. |
Availability - TPA_Extensions
| Name | Type | Description |
|---|---|---|
RequireSeriesCode |
boolean |
Required If true, the CVV code is required for the given rate. |
Timespan
| Name | Type | Description |
|---|---|---|
Start |
date, time, or datetime |
Required The starting value of the time span. |
End |
date, time, or datetime |
Required The ending value of the time span. |
BasicPropertyInfo
| Name | Type | Description |
|---|---|---|
HotelCode |
complex |
Required Refer to the HotelRef element described in Search. |
Address |
complex |
Refer to Search. |
ContactNumbers |
complex |
Refer to Search. |
Relationship between RoomID and RatePlanID
The combination of these IDs must be unique per RoomStay. IDs with the same values can be redefined in multiple RoomStays.
<OTA_HotelAvailRS>
<Success/>
<!-- Hotel #1 with 3 rates -->
<RoomStays>
<RoomStay>
<RoomTypes>
<RoomType RoomID="RT1">...</RoomType>
<RoomType RoomID="RT2">...</RoomType>
</RoomTypes>
<RatePlans> <!-- Contains cancellation policy info, guarantee type etc. -->
<RatePlan AvailabilityStatus="AvailableForSale" PrepaidIndicator="false" RatePlanID="RP1">...</RatePlan>
<RatePlan AvailabilityStatus="AvailableForSale" PrepaidIndicator="false" RatePlanID="RP2">...</RatePlan>
<RatePlan AvailabilityStatus="AvailableForSale" PrepaidIndicator="false" RatePlanID="RP3">...</RatePlan>
</RatePlans>
<RoomRates> <!-- Represents unique rate (hotel room), contains description part 1, rate cost & supported credit card etc. -->
<RoomRate RatePlanID="RP1" RoomID="RT1">...</RoomRate>
<RoomRate RatePlanID="RP2" RoomID="RT2">...</RoomRate> <!-- Note: RT2 is reused in two Room Rates -->
<RoomRate RatePlanID="RP3" RoomID="RT2">...</RoomRate>
</RoomRates>
...
</RoomStay>
</RoomStays>
<!-- Hotel #2 with 2 rates -->
<RoomStays>
<RoomStay>
<RoomTypes>
<RoomType RoomID="RT1">...</RoomType>
<RoomType RoomID="RT2">...</RoomType>
</RoomTypes>
<RatePlans>
<RatePlan AvailabilityStatus="AvailableForSale" PrepaidIndicator="false" RatePlanID="RP1">...</RatePlan>
<RatePlan AvailabilityStatus="AvailableForSale" PrepaidIndicator="false" RatePlanID="RP2">...</RatePlan>
</RatePlans>
<RoomRates>
<RoomRate RatePlanID="RP1" RoomID="RT1">...</RoomRate>
<RoomRate RatePlanID="RP2" RoomID="RT2">...</RoomRate>
</RoomRates>
...
</RoomStay>
</RoomStays>
...
</OTA_HotelAvailRS>
Descriptive Information
Descriptive Info
Message to retrieve descriptive details about a given hotel. This may include text and/or a number of URL pointed to hosted images. Concur does not host any hotel images.
| SOAPAction | OTA Name | Message Structure |
|---|---|---|
| detail | HotelDescriptiveInfo | OTA_HotelDescriptiveInfoRQ |
Descriptive Info Request
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>user</userid>
<password>password</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_HotelDescriptiveInfoRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="3" PrimaryLangID="de" AltLangID="de">
<POS>
<Source ISOCurrency="USD">
<RequestorID Type="1" ID="123"></RequestorID>
</Source>
</POS>
<HotelDescriptiveInfos>
<HotelDescriptiveInfo ChainCode="AB" HotelCode="2575"></HotelDescriptiveInfo>
</HotelDescriptiveInfos>
</OTA_HotelDescriptiveInfoRQ>
</Body>
</Envelope>
OTA_HotelDescriptiveInfoRQ
| Name | Type | Description |
|---|---|---|
HotelDescriptiveInfos |
complex |
Required Collection of items for data from multiple hotels. SAP Concur will only ever send one (1) HotelDescriptiveInfo. |
HotelDescriptiveInfos
| Name | Type | Description |
|---|---|---|
HotelDescriptiveInfo |
complex |
Required This allows the requestor to indicate which specific information is requested if complete hotel details are not required. |
HotelDescriptiveInfo
| Name | Type | Description |
|---|---|---|
ChainCode |
stringLength1to8 |
The code that identifies a hotel chain or management group. The hotel chain code is decided between vendors. This attribute is optional if the hotel is an independent property that can be identified by the HotelCode attribute. |
HotelCode |
stringLength1to16 |
Required The code that uniquely identifies a single hotel property. The hotel code is decided between vendors. |
Descriptive Info Response
The maximum allowed size of OTA_HotelDescriptiveInfoRS is 150 KB. Any response that exceeds this limit will be dropped.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_HotelDescriptiveInfoRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="3">
<Success/>
<HotelDescriptiveContents>
<HotelDescriptiveContent ChainCode="ZZ" HotelCode="2575" HotelName="Torbräu">
<HotelInfo>
<Descriptions>
<DescriptiveText>Hotel description</DescriptiveText>
</Descriptions>
</HotelInfo>
<MultimediaDescriptions>
<MultimediaDescription>
<ImageItems>
<ImageItem>
<ImageFormat>
<URL>http://image_path.jpg</URL>
</ImageFormat>
</ImageItem>
</ImageItems>
</MultimediaDescription>
</MultimediaDescriptions>
<TPA_Extensions>
<Description Name="This will be a header">
<Text>First line of first description.</Text>
<Text>Second line of first description.</Text>
</Description>
<Description>
<Text>Second description without name.</Text>
</Description>
</TPA_Extensions>
</HotelDescriptiveContent>
</HotelDescriptiveContents>
</OTA_HotelDescriptiveInfoRS>
</soap:Body>
</soap:Envelope>
OTA_HotelDescriptiveInfoRS
| Name | Type | Description |
|---|---|---|
HotelDescriptiveContents |
complex |
Required Contains hotel details content which is made up of text and image URLs. |
HotelDescriptiveContents
| Name | Type | Description |
|---|---|---|
HotelDescriptiveContent |
`complex | Required Contains hotel details content which is made up of text and image URLs. SAP Concur expects one (1) HotelDescriptiveContent. |
HotelDescriptiveContent
| Name | Type | Description |
|---|---|---|
HotelCode |
stringLength1to16 |
Required The code that uniquely identifies a single hotel property. The hotel code is decided between vendors. |
HotelName |
stringLength1to128 |
Required A text field used to communicate the proper name of the hotel. SAP Concur always expects the Hotel Name to be provided. |
TPA_Extensions |
complex |
SAP Concur specific extensions. |
MultimediaDescriptions |
complex |
Multimedia information about a collection of multimedia objects. SAP Concur expects one (1) MultimediaDescription element. |
Descriptive Info - TPA_Extensions
| Name | Type | Description |
|---|---|---|
Description |
complex |
Represents text which will be rendered in the UI in the form of a heading and a paragraph. |
Description
| Name | Type | Description |
|---|---|---|
name |
stringLength1to64 |
The contents of this element will be rendered as a heading on the hotel details page. |
Text |
stringLength1to255 |
Required The contents of this element will be rendered as a paragraph. SAP Concur expects a maximum of 20 text elements per description, which will be concatenated to into one (1) paragraph. |
MultimediaDescriptions
| Name | Type | Description |
|---|---|---|
MultimediaDescription |
complex |
Holds a list of ImageItems, each representing a single hotel image. |
MultimediaDescription
| Name | Type | Description |
|---|---|---|
ImageItems |
complex |
Holds a list of ImageItem, each representing a single hotel image. SAP Concur expects up to a maximum of 200 ImageItem elements. |
ImageItems
| Name | Type | Description |
|---|---|---|
ImageItem |
complex |
One (1) ImageItem per hotel image. |
ImageItem
| Name | Type | Description |
|---|---|---|
ImageFormat |
complex |
Format of image. |
ImageFormat
| Name | Type | Description |
|---|---|---|
URL |
stringLength1to32 |
Required Contains a HTTPS URL pointing to a hotel image. The URLs are used in a client-side gallery widget, which works best with .png and .jpg files. |
Rate Details
Message to retrieved the details of a hotel rate.
| SOAPAction | OTA Name | Message Structure |
|---|---|---|
| ratedetails | HotelAvail | OTA_HotelAvailRQ |
- Request
- Response
- Schema
- Room Stays
- Room Stay
- Room Types
- Room Type
- Room Descriptions
- Rate Plans
- Rate Plan
- Rate Plan Description
- Guarantee
- Supported Guarantee Types
- Supported Guarantee Required
- Deadline
- Cancel Penalties
- Cancel Penalty
- Meals Included
- Rooms Rates
- Room Rate
- Rates
- Rate
- RoomRateDescription
- Payment Policies
- Guarantee Payment
- Accepted Payments
- Accepted Payment
- Payment Card
- Card Type
- Total
- Rate Descriptions
- TPA Extensions
- Timespan
- Basic Property Info
Rate Details Request
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>user</userid>
<password>password</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_HotelAvailRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="5"
PrimaryLangID="de" AltLangID="de" RateDetailsInd="true">
<POS>
<Source ISOCurrency="USD">
<RequestorID Type="1" ID="1234567"></RequestorID>
</Source>
</POS>
<AvailRequestSegments>
<AvailRequestSegment>
<HotelSearchCriteria>
<Criterion>
<RatePlanCandidates>
<RatePlanCandidate RatePlanID="XNFYP4I">
<HotelRefs>
<HotelRef ChainCode="ZZ" HotelCode="111222"></HotelRef>
</HotelRefs>
</RatePlanCandidate>
</RatePlanCandidates>
</Criterion>
</HotelSearchCriteria>
<StayDateRange Start="2018-10-26" End="2018-10-28"></StayDateRange>
<RoomStayCandidates>
<RoomStayCandidate>
<GuestCounts>
<GuestCount AgeQualifyingCode="10" Count="1"></GuestCount>
</GuestCounts>
</RoomStayCandidate>
</RoomStayCandidates>
<TPA_Extensions>
<SearchSessionToken>5EA6C45E55104704E4</SearchSessionToken>
</TPA_Extensions>
</AvailRequestSegment>
</AvailRequestSegments>
</OTA_HotelAvailRQ>
</Body>
</Envelope>
Rate Details Schema
OTA_HotelAvailRQ
| Name | Type | Description |
|---|---|---|
RateDetailsInd |
boolean |
Required Always set to true for ratedetails. |
AvailRequestSegments |
complex |
Required A collection of AvailRequestSegment. Each segment includes a collection of criteria that requests a bookable entity, which may include designated rate plans, room types, amenities or services. The request can be used for guest rooms or other inventory items for which availability is sought. Each segment will be presumed to have a unique date range for each request. SAP Concur will only ever send one AvailRequestSegments. |
Rate Details - AvailRequestSegments
| Name | Type | Description |
|---|---|---|
AvailRequestSegment |
complex |
Required To accommodate the ability to perform multiple requests within one message, the availability request contains the repeating element, AvailRequestSegment. Each segment includes a collection of criteria that requests a bookable entity, which may include designated rate plans, room types, amenities or services. The request can be used for guest rooms or other inventory items for which availability is sought. Each segment will be presumed to have a unique date range for each request. SAP Concur will only ever send one AvailRequestSegment. |
Rate Details - AvailRequestSegment
| Name | Type | Description |
|---|---|---|
HotelSearchCriteria |
complex |
Required Specified hotel search criteria. SAP Concur will send only one (1) HotelSearchCriteria. |
StayDateRange |
complex |
Range of dates using ISO 8601. |
TPA_Extensions/SearchSessionToken |
stringLength1to128 |
The token obtained from Search response that links the Search results to Availability and Reservation requests. |
Rate Details - HotelSearchCriteria
| Name | Type | Description |
|---|---|---|
Criterion |
complex |
Required Refer to Criterion in Search. Note that for Rate Details the Criterion will only have one RatePlanCandidate element. |
Rate Details - Criterion
| Name | Type | Description |
|---|---|---|
RatePlanCandidates/RatePlanCandidate |
complex |
Required Specified rate plan candidate. |
Rate Details - RatePlanCandidate
| Name | Type | Description |
|---|---|---|
RatePlanID |
StringLength1to64 |
Required The code that uniquely identifies the rate plan. |
HotelRefs/HotelRef/HotelCode |
stringLength1to16 |
The code that uniquely identifies a single hotel property. The hotel code is decided by vendors. |
HotelRefs/HotelRef/ChainCode |
stringLength1to8 |
The code that identifies a hotel chain or management group. The hotel chain code is decided between vendors. This attribute is optional if the hotel is an independent property that can be identified by the HotelCode attribute. |
Rate Details - StayDateRange
| Name | Type | Description |
|---|---|---|
Start |
date, or time, or datetime |
Required The starting value of the time span. |
End |
date, or time, or datetime |
Required The ending value of the time span. |
Rate Details - RoomStayCandidates
| Name | Type | Description |
|---|---|---|
RoomStayCandidate |
complex |
Required Element used to identify available room products. |
Rate Details - RoomStayCandidate
| Name | Type | Description |
|---|---|---|
GuestCounts |
complex |
Required A collection of guest counts associated with room stay. |
Rate Details - GuestCounts
| Name | Type | Description |
|---|---|---|
GuestCount |
complex |
Required A recurring element that identifies the number of guests and ages of the guests. It currently contains hardcoded values only. See GuestCount below. |
Rate Details - GuestCount
| Name | Type | Description |
|---|---|---|
Count |
integer |
Required SAP Concur only supports one guest. Supported values: 1 |
AgeQualifyingCode |
integer |
Required Supported values: 10 |
Rate Details - Response
The maximum allowed size of OTA_HotelAvailRS is 5 MB. Any response that exceeds this limit shall be dropped.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_HotelAvailRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="5">
<Success/>
<RoomStays>
<RoomStay>
<RoomTypes>
<RoomType RoomID="1">
<RoomDescription>
<Text>Test room description.</Text>
</RoomDescription>
</RoomType>
</RoomTypes>
<RatePlans>
<RatePlan RatePlanID="XNFYP4I" AvailabilityStatus="ChangeDuringStay">
<Guarantee>
<Deadline AbsoluteDeadline="2017-01-26T18:00:00"/>
</Guarantee>
<CancelPenalties>
<CancelPenalty>
<Deadline AbsoluteDeadline="2017-01-26T18:00:00"/>
<PenaltyDescription>
<Text>REFUNDABLE</Text>
<Text>test cancel description</Text>
</PenaltyDescription>
</CancelPenalty>
</CancelPenalties>
<MealsIncluded Breakfast="true"/>
<RatePlanDescription>
<Text>Test rate plan description.</Text>
</RatePlanDescription>
</RatePlan>
</RatePlans>
<RoomRates>
<RoomRate RoomID="1" RatePlanID="XNFYP4I">
<RoomRateDescription>
<Text>Basic Wifi Included.</Text>
</RoomRateDescription>
<Rates>
<Rate RateTimeUnit="FullDuration" EffectiveDate="2018-10-26" ExpireDate="2018-10-27">
<PaymentPolicies>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="VI"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
</PaymentPolicies>
<Total AmountAfterTax="199.00" AmountBeforeTax="149.00" CurrencyCode="EUR" DecimalPlaces="2"/>
<RateDescription>
<Text>Test rate description. Both before and after tax.</Text>
</RateDescription>
<TPA_Extensions>
<RequireSeriesCode>true</RequireSeriesCode>
</TPA_Extensions>
</Rate>
<Rate RateTimeUnit="FullDuration" EffectiveDate="2018-10-27" ExpireDate="2018-10-28">
<Total AmountAfterTax="149.00" AmountBeforeTax="99.00" CurrencyCode="EUR" DecimalPlaces="2"/>
</Rate>
</Rates>
</RoomRate>
</RoomRates>
<TimeSpan End="2018-10-28" Start="2018-10-26"/>
<BasicPropertyInfo ChainCode="ZZ" HotelCode="419430"/>
</RoomStay>
</RoomStays>
<TPA_Extensions RateDetailsInd="true"></TPA_Extensions>
</OTA_HotelAvailRS>
</soap:Body>
</soap:Envelope>
Rate Details - Schema
OTA_HotelAvailRS
| Name | Type | Description |
|---|---|---|
RoomStays |
complex |
Required A collection of details on the room stay including time span of this room stay, and financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties. |
TPA_Extensions/RateDetailsInd |
boolean |
Always set to true for ratedetails. |
Rate Details - RoomStays
| Name | Type | Description |
|---|---|---|
RoomStay |
complex |
Required Details on the room stay including time span of this room stay, and financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties. A room stay represents one (1) hotel. |
Rate Details - RoomStay
For a description of the relationship between the RoomID and RatePlanID refer to "Relationship between RoomID and RatePlanID".
| Name | Type | Description |
|---|---|---|
RoomTypes |
complex |
Required Details on the room stay including guest counts, time span of this room stay, guest memberships, comments, and special requests pertaining to this particular room stay. Financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties. |
RatePlans |
complex |
Required A collection of rate plans associated with a particular room stay. The rate plan element is used to contain all the rate information for a single rate plan Code (example: RACK) for a given date range. A given rate plan may have variable rates, over the effective period of the rate plan, this is represented by the child element rates. |
RoomRates |
complex |
Required List of room rates. |
TimeSpan |
datetimespan |
Required The time span which covers the room stay. The attributes of the OTA DateTimeSpan data type are based on the W3C base data types of timeInstant and timeDuration using ISO 8601. |
BasicPropertyInfo |
complex |
Property Information for the room stay. |
Rate Details - RoomTypes
| Name | Type | Description |
|---|---|---|
RoomType |
complex |
Required Provides details regarding rooms, usually guest rooms. The room description text will be used for each room (defined as a RoomRate) which specifies the same RoomID. |
Rate Details - RoomType
| Name | Type | Description |
|---|---|---|
RoomID |
stringLength1to16 |
Required A string value representing the unique identification of a room if the request is looking for a specific room type. |
RoomDescription |
complex |
Textual information regarding the room. |
Rate Details - RoomDescription
| Name | Type | Description |
|---|---|---|
Text |
stringLength1to32 |
Required Only one (1) text element is supported. If multiple text elements are specified, the last one is used and all others are dropped. All text passed is HTML encoded. |
Rate Details - RatePlans
| Name | Type | Description |
|---|---|---|
RatePlan |
complex |
Required Defines the details of the rate plan as used in the booking process. Policies and descriptions that apply to a rate plan. Information significant to defining a rate plan. |
Rate Details - RatePlan
| Name | Type | Description |
|---|---|---|
RatePlanID |
stringLength1to64 |
Required A text field used to indicate a special ID code that is associated with the rate and is essential in the reservation request in order to obtain the rate. Examples: Corporate ID. |
AvailabilityStatus |
stringLength1to32 |
Required Used to specify an availability status for the rate plan. Supported values: AvailableForSale, ChangeDuringStay. |
Guarantee |
complex |
Required Guarantee information that applies to the rate plan. SAP Concur only expects one (1) Guarantee element per RatePlan. |
CancelPenalties |
complex |
Required if RateDetailsInd is true Collection of cancellation penalties. If the cancel penalties are not provided SAP Concur will display: "Cancellation policy not provided by vendor". |
MealsIncluded |
complex |
Required if RateDetailsInd is true Defines which meals are included with this rate program. |
RatePlanDescription |
complex |
Textual information regarding the Rate Plan. |
Rate Details - RatePlanDescription
| Name | Type | Description |
|---|---|---|
Text |
stringLength1to32 |
Required Only one (1) text element is supported. If multiple text elements are specified, the last one is used and all others are dropped. All text passed is HTML encoded. |
Rate Details - Guarantee
| Name | Type | Description |
|---|---|---|
GuaranteeType |
string |
Required The guarantee information to hold a reservation. |
Deadline |
complex |
Required Guarantee deadline, absolute or relative. |
Rate Details - Supported GuaranteeTypes
| GuaranteeType | Description |
|---|---|
Deposit |
In SAP Concur this value is seen as RequiredDeposit. |
DepositRequired |
In SAP Concur this value is seen as RequiredDeposit. |
CC/DC/Voucher |
In SAP Concur this value is seen as RequiredGuarantee. |
PrePay |
In SAP Concur this value is seen as RequiredPrepay. |
None |
In SAP Concur this value is seen as Never. No guarantee is required if user books a room with this type. |
GuaranteeRequired |
RequiredGuarantee. If the Guarantee type cannot be mapped to any accepted type, it will be set to RequiredGuarantee. This value is the default. |
Rate Details - Supported GuaranteeRequired
| GuaranteeRequired | Description |
|---|---|
always |
Guarantee is required all the time independently on deposit account setting. |
never |
Guarantee is never required. |
default |
Guarantee is required if no deposit account is set up. |
Rate Details - Deadline
| Name | Type | Description |
|---|---|---|
AbsoluteDeadline |
time or datetime |
Required Defines the absolute deadline. Either this or the offset attributes may be used. |
Rate Details - CancelPenalties
| Name | Type | Description |
|---|---|---|
CancelPenalty |
complex |
Required Defines the cancellation penalty of the hotel facility. |
Rate Details - CancelPenalty
| Name | Type | Description |
|---|---|---|
PenaltyDescription |
complex |
Text description of the penalty in a given language. This element may contain a maximum of 9 children text fields. Any excess text elements are dropped. |
Deadline |
complex |
Required Cancellation deadline, absolute or relative. See Deadline above. |
Rate Details - PenaltyDescription
| Name | Type | Description |
|---|---|---|
Text |
formattedText |
Required Formatted text content in a given language. All text passed is HTML encoded. |
Rate Details - MealsIncluded
| Name | Type | Description |
|---|---|---|
Breakfast |
boolean |
Required If true, indicates breakfast is included. If false, indicates it is excluded. In both cases this information is shown to a customer in the rate description. |
Rate Details - RoomRates
| Name | Type | Description |
|---|---|---|
RoomRate |
complex |
Required Contains the rate details. |
Rate Details - RoomRate
| Name | Type | Description |
|---|---|---|
RoomID |
complex |
Required Room Type ID. The combination of RoomID and RatePlanID must be unique for a RoomStay. |
RatePlanID |
complex |
Required Rate plan ID for which this rate is applicable for. |
Rates |
complex |
Required Contains the rate for the given room. SAP Concur only expects one (1) Rate inside the Rates element if AvailabilityStatus is AvailableForSale. It is optional to include multiple Rate for ChangeDuringStay |
RoomRateDescription |
complex |
The description or name of a room rate. |
Rate Details - Rates
| Name | Type | Description |
|---|---|---|
Rate |
complex |
Required Contains the rate for the given room. Only one (1) Rate element is expected if AvailabilityStatus is AvailableForSale. It is optional to include multiple Rate for ChangeDuringStay |
Rate Details - Rate
| Name | Type | Description |
|---|---|---|
RateTimeUnit |
string |
Indicates the time unit for the rate. Supported values: FullDuration, Day. Default: FullDuration |
EffectiveDate |
date, or time, or datetime |
For ChangeDuringStay. The starting value of the time span. |
ExpireDate |
date, or time, or datetime |
For ChangeDuringStay. The starting value of the time span. |
PaymentPolicies |
complex |
Payment policies for this rate. |
Total |
complex |
Required A description of the rate. |
RateDescription |
complex |
A textual description of a rate. Only one (1) Rate Description element is expected. |
TPA_extensions |
complex |
TPA extensions for a rate. |
Rate Details - RoomRateDescription
| Name | Type | Description |
|---|---|---|
Text |
formattedText |
Required Formatted text content in a given language. All text passed is HTML encoded. |
Rate Details - PaymentPolicies
| Name | Type | Description |
|---|---|---|
GuaranteePayment |
complex |
Element containing the guarantee payment type. |
Rate Details - GuaranteePayment
| Name | Type | Description |
|---|---|---|
AcceptedPayments |
complex |
Required If used, at least one (1) AcceptedPayment should be present. |
Rate Details - AcceptedPayments
| Name | Type | Description |
|---|---|---|
AcceptedPayment |
complex |
Required Accepted payment type. |
Rate Details - AcceptedPayment
| Name | Type | Description |
|---|---|---|
PaymentCard |
complex |
Required Description of payment type. |
Rate Details - PaymentCard
| Name | Type | Description |
|---|---|---|
CardType |
complex |
Required String representation of a card type. Allowed values: AmericanExpress, BankOfAmerica, BritishAirways, CapitalOne, Chase, Citibank, ContinentalAirlines, DeltaAirlines, DiscoverCard, Disney, Eurocard, Hilton, Hyatt, Mariott, Mastercard, RitzCarlton, SouthwestAirlines, StarwoodHotels, UnitedAirlines, USAirways, VISA, Other_. See Code and Description if card type is other_. |
Rate Details - CardType
| Name | Type | Description |
|---|---|---|
Code |
string |
If CardType is Other_, use this attribute for card code. Examples: AX, VI. |
Description |
string |
If CardType is Other_, use this attribute for card description. |
Rate Details - Total
| Name | Type | Description |
|---|---|---|
AmountBeforeTax |
string |
Required The total amount not including any associated tax. Examples: sales tax, VAT, GST |
AmountAfterTax |
string |
Required The total amount including all associated taxes. Examples: sales tax, VAT, GST |
CurrencyCode |
alphaLength3 |
Required Currency code. |
DecimalPlaces |
integer |
Decimal places for currency code. This is an ISO 4217 standard "minor unit" for the number of decimal places for a particular currency. |
Rate Details - RateDescription
| Name | Type | Description |
|---|---|---|
Text |
stringLength1to32 |
Required SAP Concur only expects one (1) text field for the rate description. Any excess text elements will be ignored. All text passed is HTML encoded. |
Rate Details - TPA_Extensions
| Name | Type | Description |
|---|---|---|
RequireSeriesCode |
boolean |
Required If true, the CVV code is required for the given rate. |
Rate Details - Timespan
| Name | Type | Description |
|---|---|---|
Start |
date, time, or datetime |
Required The starting value of the time span. |
End |
date, time, or datetime |
Required The ending value of the time span. |
Rate Details - BasicPropertyInfo
| Name | Type | Description |
|---|---|---|
HotelCode |
complex |
Required Refer to the HotelRef element described in Search. |
Address |
complex |
Refer to Search. |
ContactNumbers |
complex |
Refer to Search. |
Reservation
Reservation Message
Message to reserve a hotel.
| SOAPAction | OTA Name | Message Structure |
|---|---|---|
| book | HotelRes | OTA_HotelResRQ |
- Request
- Schema
- Hotel Reservation
- Room Stays
- Guest Counts
- Guest Count
- Rate Plan
- Guarantee
- Guarantees Accepted
- Payment Card
- Series Code
- Comments
- Comment
- Text
- Res Guest
- Profile
- Customer
- Person Name
- Telephone
- Citizen Country Name
- Company Info
- Res Global Info
- Memberships
- Membership
- Comments
- Comment
- TPA Extensions
- Notify Emails
- Custom Fields
- Custom Field
- Response
Reservation Request
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>user</userid>
<password>password</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_HotelResRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="6"
PrimaryLangID="de" AltLangID="de">
<POS>
<Source ISOCurrency="USD">
<RequestorID Type="4" ID="s1"></RequestorID>
</Source>
</POS>
<HotelReservations>
<HotelReservation>
<RoomStays>
<RoomStay>
<RatePlans>
<RatePlan RatePlanID="ZZZZ1117">
<Guarantee GuaranteeType="CC/DC/Voucher">
<GuaranteesAccepted>
<GuaranteeAccepted>
<PaymentCard CardCode="VI" ExpireDate="1018">
<CardType Code="VI">VISA</CardType>
<CardHolderName>Jane Doe</CardHolderName>
<Address>
<StreetNmbr>600 13TH ST NE</StreetNmbr>
<CityName>WASHINGTON</CityName>
<PostalCode>20002</PostalCode>
<StateProv StateCode="DC"></StateProv>
<CountryName>US</CountryName>
</Address>
<SeriesCode>
<PlainText>xxx</PlainText>
</SeriesCode>
</PaymentCard>
</GuaranteeAccepted>
</GuaranteesAccepted>
</Guarantee>
</RatePlan>
</RatePlans>
<TimeSpan Start="2017-01-26" End="2017-01-27"></TimeSpan>
<BasicPropertyInfo HotelCode="111222"></BasicPropertyInfo>
<Comments>
<Comment>
<Text TextFormat="PlainText">ROLLAWAY</Text>
</Comment>
<Comment>
<Text TextFormat="PlainText">FOAMPILLOWS</Text>
</Comment>
</Comments>
</RoomStay>
</RoomStays>
<ResGuests>
<ResGuest>
<Profiles>
<ProfileInfo>
<Profile>
<Customer Gender="Female" BirthDate="1987-05-12">
<PersonName Language="de">
<NamePrefix>MRS</NamePrefix>
<GivenName>JANE</GivenName>
<Surname>DOE</Surname>
</PersonName>
<Telephone PhoneNumber="703-837-6100"></Telephone>
<Email>jane.doe@example.com</Email>
<Address>
<AddressLine>209 Madison St Suite 400</AddressLine>
<CityName>Alexandria</CityName>
<PostalCode>22314</PostalCode>
<StateProv StateCode="VA"></StateProv>
<CountryName Code="US">USA</CountryName>
</Address>
<CitizenCountryName Code="US"></CitizenCountryName>
</Customer>
<CompanyInfo>
<CompanyName>SAP Concur</CompanyName>
</CompanyInfo>
</Profile>
</ProfileInfo>
</Profiles>
<GuestCounts>
<GuestCount Count="1"></GuestCount>
</GuestCounts>
</ResGuest>
</ResGuests>
<ResGlobalInfo>
<Memberships>
<Membership ProgramCode="HotelLoyaltyProgram" AccountID="1111111"></Membership>
</Memberships>
</ResGlobalInfo>
<TPA_Extensions>
<SearchSessionToken>5EA6C45E55104704E4</SearchSessionToken>
</TPA_Extensions>
</HotelReservation>
<TPA_Extensions>
<NotifyEmails>
<NotifyEmails>jane.doe@example.com</NotifyEmails>
<NotifyEmails>a@b.cz</NotifyEmails>
<NotifyEmails>d@f.cz</NotifyEmails>
</NotifyEmails>
<CustomFields>
<CustomField Name="trip1" Value="value1t"></CustomField>
<CustomField Name="trip2" Value="value2t"></CustomField>
<CustomField Name="user1" Value="value1u"></CustomField>
<CustomField Name="user2"></CustomField>
</CustomFields>
</TPA_Extensions>
</HotelReservations>
</OTA_HotelResRQ>
</Body>
</Envelope>
OTA_HotelResRQ
| Name | Type | Description |
|---|---|---|
HotelReservations |
complex |
Required A collection of hotel reservations. SAP Concur will only send one (1) hotel reservation. |
Reservation - HotelReservation
| Name | Type | Description |
|---|---|---|
RoomStays |
complex |
Required A reference to identify the booking. |
ResGuests |
complex |
Required List of guests. Supported value: 1 |
ResGlobalInfo |
complex |
Contains information that affects the reservation as a whole, typically a list of reward programs (see Memberships) or itinerary remarks (see Comments). |
TPA_Extensions/SearchSessionToken |
stringLength1to128 |
The token obtained from Search response that links the Search results to Availability and Reservation requests. |
RoomStays
| Name | Type | Description |
|---|---|---|
RatePlans |
complex |
Required Refer to RatePlans in Availability. |
Timespan |
complex |
Required Refer to Time-span in Availability. |
BasicPropertyInfo |
complex |
Required See Availability. |
Comments |
complex |
Comments from the user which are passed on to the hotel. |
Reservation - GuestCounts
| Name | Type | Description |
|---|---|---|
GuestCounts |
complex |
Required Please note: this field is currently being discussed with our partners as the plan to remove GuestCounts from OTA_HotelAvailRQ. A recurring element that identifies the number of guests. |
Reservation - GuestCount
| Name | Type | Description |
|---|---|---|
Count |
integer |
Required Please note: this element is planned to be removed. A recurring element that identifies the number of guests and ages of the guests. The number of guests. Supported value: 1 |
RatePlan
| Name | Type | Description |
|---|---|---|
RatePlanID |
stringLength1to64 |
A text field used to provide a special ID code that is associated with the rate and is required in the reservation request in order to obtain the rate. |
Guarantee |
complex |
Required Refer to Guarantee in Availability. |
Reservation - Guarantee
| Name | Type | Description |
|---|---|---|
GuaranteeType |
stringLength1to32 |
Required Refer to GuaranteeType in Availability. |
GuaranteesAccepted |
complex |
Required Guarantee and payment information. |
GuaranteesAccepted
| Name | Type | Description |
|---|---|---|
Default |
boolean |
This is to indicate that the information in the model is the default (e.g. if PaymentCard information is completed then this would be considered the default if the boolean is true). |
NoCardHolderInfoReqInd |
boolean |
If true, no credit card holder information is required. If false, it is required. |
NameReqInd |
boolean |
If true, the credit card holder name is required. If false, it is not required. |
AddressReqInd |
boolean |
If true, credit card holder address is required. If false, it is not required. |
PhoneReqInd |
boolean |
If true, credit card holder phone number is required. If false, it is not required. |
InterbankNbrReqInd |
boolean |
If true, the credit card interbank number is required. If false, it is not required. |
PaymentCard |
complex |
Required Specific payment card information. |
Reservation - PaymentCard
| Name | Type | Description |
|---|---|---|
CardCode |
upperCaseAlphaLength1to2 |
Issuer code. Example: MC, VI, AX. |
ExpireDate |
MMYYDate |
Indicates the ending date. |
CardType |
stringLength1to32 |
Required Payment card type. Example: MasterCard |
CardHolderName |
stringLength1to32 |
Required Card holder name. |
CardNumber |
complex |
Required The card number. |
Address |
complex |
Required Refer to Address in Search. |
SeriesCode |
complex |
Verification digits. |
SeriesCode
| Name | Type | Description |
|---|---|---|
PlainText |
stringLength1to32 |
Required CVV number. Only one (1) element of this type is sent. |
Comments
| Name | Type | Description |
|---|---|---|
Comment |
complex |
Required SAP Concur will send one Text element per Comment element. |
Comment
| Name | Type | Description |
|---|---|---|
Text |
string |
Required Text representing the comment. |
Text
| Name | Type | Description |
|---|---|---|
TextFormat |
stringLength1to32 |
Required Supported value: Plain text |
ResGuest
| Name | Type | Description |
|---|---|---|
Profiles |
complex |
Required List of Profiles. SAP Concur will only send one (1) profile. |
Profile
| Name | Type | Description |
|---|---|---|
Customer |
complex |
Required Element to describer a customer. |
CompanyInfo |
complex |
Element to capture the company name. |
Customer
| Name | Type | Description |
|---|---|---|
Gender |
string |
Gender. Supported values: Male, Female, Unknown, Male_NoShare, Female_NoShare |
BirthDate |
date |
Customer's birthday. |
PersonName |
complex |
Element representing a customer's name. |
Telephone |
complex |
Element representing a telephone number. |
Email |
stringLength1to32 |
Email address. |
Address |
complex |
Refer to Address in Search. |
CitizenCountryName |
complex |
ISO 3166 representation of the user's country as defined in their SAP Concur Profile. |
PersonName
| Name | Type | Description |
|---|---|---|
NamePrefix |
stringLength1to16 |
Salutation of honorific. Supported values: Mr, Mrs, Ms, Miss, Dr, Rev, Sir, Lord, Lady, Dr Mr, Dr Mrs, Dr Ms, Prof Mr, Prof Mrs, Prof Ms, Prof Dr Mr, Prof Dr Mrs, Prof Dr Ms |
GivenName |
stringLength1to64 |
Given name, first name or names. |
Surname |
stringLength1to64 |
Required Family name, last name. May also be used for full name if the sending system does not have the ability to separate a full name into its parts. Example: the surname element may be used to pass the full name. |
Telephone
| Name | Type | Description |
|---|---|---|
PhoneNumber |
stringLength1to32 |
Required A string representing a customer's phone number. |
CitizenCountryName
| Name | Type | Description |
|---|---|---|
Code |
stringLength1to32 |
Required ISO 3166 country code. |
CompanyInfo
| Name | Type | Description |
|---|---|---|
CompanyName |
stringLength1to32 |
Required A string representing a customer's company. |
ResGlobalInfo
Note: This structure is used in both request and response. Different elements are used in each of them.
| Name | Type | Description |
|---|---|---|
Memberships |
complex |
Request Only A collection of memberships. Provides a list of reward programs. Example: loyalty cards |
Comments |
complex |
Response Only A collection of comments. Provides a list of arbitrary reservation comments. Example: modification code |
BasicPropertyInfo |
complex |
See Availability. |
Memberships
| Name | Type | Description |
|---|---|---|
Membership |
complex |
A recurring element that identifies the type of reservation comment. |
Membership
| Name | Type | Description |
|---|---|---|
ProgramCode |
stringLength1to32 |
Required The code or name of the reward program. Example: HotelLoyaltyProgram |
AccountID |
stringLength1to64 |
Required The account identification number for this particular member in this particular program. |
Comments
| Name | Type | Description |
|---|---|---|
Comment |
complex |
A recurring element that carries reservation comment. Maximum elements: 9 |
Comment
| Name | Type | Description |
|---|---|---|
Name |
stringLength1to64 |
Attribute containing comment title. |
Text |
string |
Required Comment payload. Up to 3 Text elements in the comment. Up to 200 characters in the text. |
Reservation - TPA Extensions
| Name | Type | Description |
|---|---|---|
NotifyEmails |
complex |
Email address which can be used by the vendor to contact the customer. |
CustomFields |
complex |
A reference to identify the booking. |
NotifyEmails
| Name | Type | Description |
|---|---|---|
NotifyEmails |
stringLength1to32 |
Required There will be one (1) NotifyEmails element per email address in the configuration. |
Reservation CustomFields
| Name | Type | Description |
|---|---|---|
CustomField |
complex |
Required A custom field in the form of a key-value pair. |
Reservation CustomField
| Name | Type | Description |
|---|---|---|
Name |
stringLength1to32 |
Required Name of the custom field. |
Value |
stringLength1to32 |
Value of the custom field. |
Reservation - Response
The maximum allowed size of OTA_HotelResRS is 150 KB. Any response that exceeds this limit shall be dropped.
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_HotelResRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="6" ResResponseType="Reserved">
<Success/>
<HotelReservations>
<HotelReservation>
<UniqueID Type="14" ID="88618333"/>
<UniqueID Type="1000" ID="12345"/>
<RoomStays>
<RoomStay>
<RatePlans>
<RatePlan RatePlanID="EZ57LL7">
<CancelPenalties CancelPolicyIndicator="true">
<CancelPenalty>
<PenaltyDescription>
<Text>test cancel policy 1</Text>
</PenaltyDescription>
</CancelPenalty>
<CancelPenalty>
<PenaltyDescription>
<Text>test cancel policy 2</Text>
</PenaltyDescription>
<PenaltyDescription>
<Text>test cancel policy 3</Text>
</PenaltyDescription>
</CancelPenalty>
<CancelPenalty>
<Deadline AbsoluteDeadline="2017-01-26T18:00"/>
</CancelPenalty>
</CancelPenalties>
</RatePlan>
</RatePlans>
<RoomRates>
<RoomRate>
<Rates>
<Rate>
<PaymentPolicies>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard>
<CardType>VISA</CardType>
</PaymentCard>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard>
<CardType>Mastercard</CardType>
</PaymentCard>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard>
<CardType>AmericanExpress</CardType>
</PaymentCard>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
</PaymentPolicies>
<Total AmountAfterTax="185.00" AmountBeforeTax="85.00" CurrencyCode="EUR"/>
</Rate>
</Rates>
</RoomRate>
</RoomRates>
<TimeSpan End="2017-01-27" Start="2017-01-26"/>
<BasicPropertyInfo HotelCode="50709" HotelName="Alexander Plaza">
<Address>
<AddressLine>Rosenstr. 1</AddressLine>
<CityName>Berlin</CityName>
<CountryName Code="DEU">Federal Republic of Germany</CountryName>
<StateProv StateCode="BE">Berlin District</StateProv>
<PostalCode>BE123</PostalCode>
</Address>
<ContactNumbers>
<ContactNumber PhoneNumber="1111111112" PhoneTechType="1"/>
</ContactNumbers>
</BasicPropertyInfo>
</RoomStay>
</RoomStays>
<ResGuests>
<ResGuest>
<Profiles>
<ProfileInfo>
<Profile>
<Customer>
<PersonName>
<GivenName>Jane</GivenName>
<Surname>Doe</Surname>
</PersonName>
</Customer>
</Profile>
</ProfileInfo>
</Profiles>
</ResGuest>
</ResGuests>
<ResGlobalInfo>
<Comments>
<Comment Name="First Comment">
<Text>First line of first comment</Text>
<Text>Second line of first comment</Text>
</Comment>
<Comment>
<Text>Second comment without name</Text>
</Comment>
</Comments>
</ResGlobalInfo>
</HotelReservation>
</HotelReservations>
</OTA_HotelResRS>
</soap:Body>
</soap:Envelope>
OTA_HotelResRS
| Name | Type | Description |
|---|---|---|
ResResponseType |
stringLength1to32 |
Required See the list of possible values. |
HotelReservations |
complex |
Required SAP Concur only supports one (1) reservation. All extra reservations will be ignored. |
ResResponseType
| Value | Description |
|---|---|
Cancelled |
- |
Committed |
- |
Unsuccessful |
- |
Reserved |
The item is reserved. |
Reservation - HotelReservations
| Name | Type | Description |
|---|---|---|
HotelReservation |
complex |
Required A reference to identify the booking. |
Reservation - HotelReservation
| Name | Type | Description |
|---|---|---|
UniqueID |
complex |
Required A reference to identify the booking. Maximum occurrences: 2 |
RoomStays |
complex |
Required A collection of details on the room stay including time span of this room stay, and financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties. |
UniqueID
| Name | Type | Description |
|---|---|---|
ID |
stringLength1to32 |
Required A reference to identify the booking. |
Type |
stringLength1to32 |
Required A reference to identify the type of UniqueID. See Type. |
Type - Possible Values
| Value | Description |
|---|---|
14 |
Reservation ID used in subsequent calls (Itinerary, Cancel). |
15 |
Cancellation number, displayed in UI, proof of cancellation. |
40 |
Confirmation number for future use (not used now). |
1000 |
Cancellation/modification code. This will be rendered on itinerary page and can be used to change the reservation outside of the SAP Concur system. SAP Concur-specific OTA extension. |
Reservation - RoomStays
| Name | Type | Description |
|---|---|---|
RoomStay |
complex |
Required Details on the room stay including time span of this room stay, pointers to res guests, comments and special requests pertaining to this particular room stay. Financial information related to the room stay, including guarantee, deposit, payment, and cancellation penalties. |
Reservation - RoomStay
| Name | Type | Description |
|---|---|---|
RatePlans |
complex |
Required A collection of rate plans associated with a particular room stay. |
Reservation - RatePlan
| Name | Type | Description |
|---|---|---|
CancelPenalties |
complex |
Collection of cancellation penalties. |
CancelPolicyIndicator |
boolean |
If true, indicates a cancel policy exists. If false, no cancel policy exists. Typically this indicator is used when details are not being sent. |
Reservation - CancelPenalty
| Name | Type | Description |
|---|---|---|
PenaltyDescription |
complex |
Text description of the penalty in a given language. Maximum elements: 9 |
Reservation - PenaltyDescription
| Name | Type | Description |
|---|---|---|
Text |
formattedTextTextType |
Formatted text content. |
Cancel
Message used to indicate to the hotel supplier that a given reservation should be cancelled.
| SOAPAction | OTA Name | Message Structure |
|---|---|---|
| cancel | Cancel | OTA_CancelRQ |
Request
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>user</userid>
<password>password</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_CancelRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="test_request_id" Version="3"
PrimaryLangID="en" AltLangID="en" CancelType="Cancel">
<POS>
<Source ISOCurrency="USD"></Source>
</POS>
<UniqueID Type="14" ID="11112222"></UniqueID>
</OTA_CancelRQ>
</Body>
</Envelope>
OTA_CancelRQ
| Name | Type | Description |
|---|---|---|
UniqueID |
`complex | Required Element to hold the type and the ID of the reservation to be cancelled. |
UniqueID
| Name | Type | Description |
|---|---|---|
Type |
string |
Required UniqueID with Type=14 identifies the reservation to cancel. |
ID |
stringLength1to32 |
Required A unique identifying value assigned by the creating system. |
Response
The maximum allowed size of OTA_CancelRS is 150 KB. Any response that exceeds this limit shall be dropped.
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_CancelRS xmlns="http://www.opentravel.org/OTA/2003/05" Version="3" Status="Cancelled">
<Success/>
<UniqueID ID="11112222" Type="14"/>
<UniqueID ID="12122" Type="15"/>
</OTA_CancelRS>
</soap:Body>
</soap:Envelope>
OTA_CancelRS
| Name | Type | Description |
|---|---|---|
Status |
string |
Required Supported values: Cancelled, Unsuccessful |
Success |
`successType | An element that is not intended to contain any data. The mere presence of a success element within the response message indicates that the incoming request message was processed successfully. |
UniqueID |
string |
Required See UniqueID above. SAP Concur expects two (2) UniqueIDs to be returned in the response. The first with an Type of 14 containing the original reservation number, and the second Type of 15 containing a confirmation number. Both elements are mandatory. |
Appendix
Search

Request
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>testLogin123</userid>
<password>txxxxxxxxxxxx;</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_HotelSearchRQ xmlns="http://www.opentravel.org/OTA/2003/05"
EchoToken="5ADE581A-8A7C-4DA5-A67B-EED4E58A80E2"
Version="4" PrimaryLangID="en" AltLangID="en" MaxResponses="100">
<POS>
<Source ISOCurrency="USD"></Source>
</POS>
<Criteria>
<Criterion>
<Position Latitude="52.559720" Longitude="13.287780"></Position>
<RefPoint></RefPoint>
<Radius Distance="5" DistanceMax="30" UnitOfMeasureCode="1"></Radius>
<StayDateRange Start="2018-02-12" End="2018-02-13"></StayDateRange>
</Criterion>
</Criteria>
</OTA_HotelSearchRQ>
</Body>
</Envelope>
Response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_HotelSearchRS xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:ns2="http://www.concur.com/webservice/auth" AltLangID="fr" EchoToken="FC6F5CDE-2D55-49A4-AE22-056AF980ADF4" PrimaryLangID="fr" Version="4">
<Success/>
<Properties>
<Property ChainName="Appart City" HotelCode="399671" HotelName="Appart'City Aix en Provence - La Duranne Residence de Tourisme">
<Position Latitude="43.49205" Longitude="5.351965"/>
<Address>
<AddressLine>300 avenue du Grand Vallat</AddressLine>
<CityName>Les Milles</CityName>
<PostalCode>13290</PostalCode>
<CountryName Code="FR">French Republic France</CountryName>
</Address>
<Award Rating="2"/>
<HotelAmenity Code="68"/>
<HotelAmenity Code="198"/>
<HotelAmenity Code="71"/>
<HotelAmenity Code="101"/>
<HotelAmenity Code="33"/>
<Policy CheckInTime="14:00:00" CheckOutTime="12:00:00"/>
<TPA_Extensions>
<HotelPreference>not_preferred</HotelPreference>
<TPA_HotelPreviewImageURI>
<URL>https://foto.hrsstatic.com/fotos/1/3/75/75/80/FFFFFF/http%3A%2F%2Ffoto-origin.hrsstatic.com%2Ffoto%2F3%2F9%2F9%2F6%2Fteaser_399671.jpg/v1M9Y02mJkgafy7d97qkhw%3D%3D/128%2C85/6/AppartCity_Aix_en_Provence_La_Duranne_Residence_de_Tourisme-Les_Milles_Aix-en-Provence-Exterior_view-3-399671.jpg</URL>
</TPA_HotelPreviewImageURI>
</TPA_Extensions>
</Property>
<Property>
... and another properties follow here for all the returned hotels
</Property>
</Properties>
</OTA_HotelSearchRS>
</soap:Body>
</soap:Envelope>
Availability
The initial Search request (see above) is followed up by an multi-property Availability request. In the example request below Concur requests the availability for 13 properties. This could because the initial search only yielded 13 properties or the configuration per vendor is set to request availability for a maximum of 13 properties.
Request
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>testLogin123</userid>
<password>txxxxxxxxxxxx;</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_HotelAvailRQ xmlns="http://www.opentravel.org/OTA/2003/05"
EchoToken="5ADE581A-8A7C-4DA5-A67B-EED4E58A80E2"
Version="5" PrimaryLangID="en" AltLangID="en">
<POS>
<Source ISOCurrency="USD"></Source>
</POS>
<AvailRequestSegments>
<AvailRequestSegment>
<HotelSearchCriteria>
<Criterion>
<HotelRef ChainCode="ZZ" HotelCode="50709"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="ZZ" HotelCode="468159"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="ZZ" HotelCode="584875"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="ZZ" HotelCode="765336"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="ZZ" HotelCode="70346"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="ZZ" HotelCode="52198"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="ZZ" HotelCode="697768"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="ZZ" HotelCode="14411"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="ZZ" HotelCode="436533"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="ZZ" HotelCode="459980"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="ZZ" HotelCode="419430"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="ZZ" HotelCode="92103"></HotelRef>
</Criterion>
<Criterion>
<HotelRef ChainCode="ZZ" HotelCode="252272"></HotelRef>
</Criterion>
</HotelSearchCriteria>
<StayDateRange Start="2018-02-12" End="2018-02-13"></StayDateRange>
<RoomStayCandidates>
<RoomStayCandidate>
<GuestCounts>
<GuestCount AgeQualifyingCode="10" Count="1"></GuestCount>
</GuestCounts>
</RoomStayCandidate>
</RoomStayCandidates>
</AvailRequestSegment>
</AvailRequestSegments>
</OTA_HotelAvailRQ>
</Body>
</Envelope>
Response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_HotelAvailRS xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:ns2="http://www.concur.com/webservice/auth" AltLangID="fr" EchoToken="FC6F5CDE-2D55-49A4-AE22-056AF980ADF4" PrimaryLangID="fr" Version="5">
<Success/>
<RoomStays>
<RoomStay>
<RoomTypes>
<RoomType RoomID="b3da298f">
<RoomDescription>
<Text>La chambre standard est équipée de douche/WC ou de baignoire/WC.</Text>
</RoomDescription>
<Amenities>
<Amenity ExistsCode="1" RoomAmenity="55"/>
<Amenity ExistsCode="1" RoomAmenity="56"/>
<Amenity ExistsCode="1" RoomAmenity="4"/>
<Amenity ExistsCode="1" RoomAmenity="28"/>
<Amenity ExistsCode="1" RoomAmenity="210"/>
<Amenity ExistsCode="1" RoomAmenity="92"/>
<Amenity ExistsCode="1" RoomAmenity="2"/>
<Amenity ExistsCode="1" RoomAmenity="126"/>
<Amenity ExistsCode="1" RoomAmenity="19"/>
<Amenity ExistsCode="1" RoomAmenity="13"/>
<Amenity ExistsCode="1" RoomAmenity="96"/>
<Amenity ExistsCode="1" RoomAmenity="50"/>
<Amenity ExistsCode="1" RoomAmenity="69"/>
<Amenity ExistsCode="1" RoomAmenity="107"/>
<Amenity ExistsCode="1" RoomAmenity="10"/>
</Amenities>
</RoomType>
</RoomTypes>
<RatePlans>
<RatePlan AvailabilityStatus="AvailableForSale" PrepaidIndicator="false" RatePlanID="TOGG3BU">
<Guarantee GuaranteeType="GuaranteeRequired">
<Deadline AbsoluteDeadline="2019-05-08T23:59:59"/>
</Guarantee>
<CancelPenalties>
<CancelPenalty NonRefundable="false">
<Deadline AbsoluteDeadline="2019-05-08T23:59:59" OffsetDropTime="BeforeArrival" OffsetTimeUnit="Day"
OffsetUnitMultiplier="14"/>
</CancelPenalty>
</CancelPenalties>
<MealsIncluded Breakfast="false" Dinner="false" Lunch="false"/>
</RatePlan>
</RatePlans>
<RoomRates>
<RoomRate RatePlanID="TOGG3BU" RoomID="b3da298f">
<Rates>
<Rate ChargeType="18" GuaranteedInd="true" NumberOfUnits="1" RateTimeUnit="FullDuration"
RoomPricingType="Per stay" UnitMultiplier="1">
<PaymentPolicies>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard>
<CardType>VISA</CardType>
</PaymentCard>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard>
<CardType>Mastercard</CardType>
</PaymentCard>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
</PaymentPolicies>
<Total AmountAfterTax="161.10" AmountBeforeTax="152.70" CurrencyCode="EUR" DecimalPlaces="2"/>
<RateDescription>
<Text>Tarif promotionnel</Text>
<Text>Gratuit pour les clients HRS: Quotidien gratuit, Parking attenant à l'hôtel</Text>
</RateDescription>
</Rate>
</Rates>
</RoomRate>
</RoomRates>
<GuestCounts>
<GuestCount Count="1"/>
</GuestCounts>
<TimeSpan End="2019-05-23" Start="2019-05-22"/>
<BasicPropertyInfo HotelCode="36151" HotelName="Château de la Pioline">
<Address>
<AddressLine>260 Rue Guillaume du Vair</AddressLine>
<CityName>AIX EN PROVENCE</CityName>
<PostalCode>13546</PostalCode>
<CountryName Code="FR">French Republic France</CountryName>
</Address>
<ContactNumbers>
<ContactNumber PhoneNumber="33442522727"/>
</ContactNumbers>
</BasicPropertyInfo>
</RoomStay>
<RoomStay>
<RoomTypes>
<RoomType RoomID="f7631619">
<RoomDescription>
<Text>La chambre standard est équipée de douche/WC ou de baignoire/WC.</Text>
</RoomDescription>
<Amenities>
<Amenity ExistsCode="1" RoomAmenity="55"/>
<Amenity ExistsCode="1" RoomAmenity="56"/>
<Amenity ExistsCode="1" RoomAmenity="4"/>
<Amenity ExistsCode="1" RoomAmenity="28"/>
<Amenity ExistsCode="1" RoomAmenity="210"/>
<Amenity ExistsCode="1" RoomAmenity="92"/>
<Amenity ExistsCode="1" RoomAmenity="2"/>
<Amenity ExistsCode="1" RoomAmenity="126"/>
<Amenity ExistsCode="1" RoomAmenity="19"/>
<Amenity ExistsCode="1" RoomAmenity="13"/>
<Amenity ExistsCode="1" RoomAmenity="96"/>
<Amenity ExistsCode="1" RoomAmenity="50"/>
<Amenity ExistsCode="1" RoomAmenity="69"/>
<Amenity ExistsCode="1" RoomAmenity="107"/>
<Amenity ExistsCode="1" RoomAmenity="10"/>
</Amenities>
</RoomType>
</RoomTypes>
<RatePlans>
<RatePlan AvailabilityStatus="AvailableForSale" PrepaidIndicator="false" RatePlanID="MB4YV34">
<Guarantee GuaranteeType="Deposit"/>
<CancelPenalties>
<CancelPenalty NonRefundable="true">
<Deadline AbsoluteDeadline="2019-04-15T12:51:47"/>
</CancelPenalty>
</CancelPenalties>
<MealsIncluded Breakfast="false" Dinner="false" Lunch="false"/>
</RatePlan>
</RatePlans>
<RoomRates>
<RoomRate RatePlanID="MB4YV34" RoomID="f7631619">
<Rates>
<Rate ChargeType="18" GuaranteedInd="true" NumberOfUnits="1" RateTimeUnit="FullDuration"
RoomPricingType="Per stay" UnitMultiplier="1">
<PaymentPolicies>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard>
<CardType>VISA</CardType>
</PaymentCard>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard>
<CardType>Mastercard</CardType>
</PaymentCard>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
</PaymentPolicies>
<Total AmountAfterTax="149.00" AmountBeforeTax="141.23" CurrencyCode="EUR" DecimalPlaces="2"/>
<RateDescription>
<Text>Hot Deal</Text>
<Text>Gratuit pour les clients HRS: Quotidien gratuit, Parking attenant à l'hôtel</Text>
</RateDescription>
</Rate>
</Rates>
</RoomRate>
</RoomRates>
<GuestCounts>
<GuestCount Count="1"/>
</GuestCounts>
<TimeSpan End="2019-05-23" Start="2019-05-22"/>
<BasicPropertyInfo HotelCode="36151" HotelName="Château de la Pioline">
<Address>
<AddressLine>260 Rue Guillaume du Vair</AddressLine>
<CityName>AIX EN PROVENCE</CityName>
<PostalCode>13546</PostalCode>
<CountryName Code="FR">French Republic France</CountryName>
</Address>
<ContactNumbers>
<ContactNumber PhoneNumber="33442522727"/>
</ContactNumbers>
</BasicPropertyInfo>
</RoomStay>
<RoomStay>
... and another RoomStay nodes follow here for all the returned rooms for all the hotels (properties) per
Availability request
</RoomStay>
</RoomStays>
</OTA_HotelAvailRS>
</soap:Body>
</soap:Envelope>
Search results displayed
Search results page displaying hotels, based on Search response, and their rates, based on Availability response:

WIth Availability response also cancellation information comes which can be displayed in separate popup:

Hotel Description

Request
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>testLogin123</userid>
<password>txxxxxxxxxxxx;</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_HotelDescriptiveInfoRQ xmlns="http://www.opentravel.org/OTA/2003/05"
EchoToken="A78F3641-8674-43F9-B58C-AD928D1A75D9"
Version="3" PrimaryLangID="en" AltLangID="en">
<POS>
<Source ISOCurrency="USD"></Source>
</POS>
<HotelDescriptiveInfos>
<HotelDescriptiveInfo ChainCode="ZZ" HotelCode="419430"></HotelDescriptiveInfo>
</HotelDescriptiveInfos>
</OTA_HotelDescriptiveInfoRQ>
</Body>
</Envelope>
Response
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_HotelDescriptiveInfoRS xmlns="http://www.opentravel.org/OTA/2003/05"
xmlns:ns2="http://www.concur.com/webservice/auth">
<Success/>
<HotelDescriptiveContents>
<HotelDescriptiveContent ChainCode="ZZ" HotelCode="419430" HotelName="Courtyard Prague Airport">
<HotelInfo>
<Descriptions>
<DescriptiveText>Prague (PRG): The Europort building which housed the hotel is located in front of the
arrivial and departure halls at Prague-ruzyne Airport. The hotel will have direct access to the
airport’s infrastructure and offer connections to both the walkway and transporation routes. The
conveniently located Courtyard Prague Airport provides its guests upscale accommodation outside the
buzzing city centre. Kept in a cosy elegant design, the comfortable rooms are fitted with coffee and tea
maker and nice sitting and working area. The magnificent atrium with its modern structure and nice
garden invites to stay and relax. Directly situated at Prague’s international airport, the hotel is
about 16 kilometres from the city centre and the historic castle. In the nearby surroundings, guests can
enjoy horseback riding, biking or kayaking. Oléo Pazzo Mediterranean Bistro is a contemporary restaurant
decorated in warm and coulourful style with a show kitchen and a trendy bar. Other features are a
fitness,a business center,meeting rooms.
</DescriptiveText>
</Descriptions>
</HotelInfo>
<MultimediaDescriptions>
<MultimediaDescription>
<ImageItems>
<ImageItem>
<ImageFormat>
<URL>http://iut-foto-origin.hrsstatic.com/foto/3/8/9/8/389886/389886_fi_451616.jpg</URL>
</ImageFormat>
</ImageItem>
<ImageItem>
<ImageFormat>
<URL>http://iut-foto-origin.hrsstatic.com/foto/3/8/9/8/389886/389886_u_6302064.jpg</URL>
</ImageFormat>
</ImageItem>
<ImageItem>
<ImageFormat>
<URL>http://iut-foto-origin.hrsstatic.com/foto/3/8/9/8/389886/389886_u_451896.jpg</URL>
</ImageFormat>
</ImageItem>
</ImageItems>
</MultimediaDescription>
</MultimediaDescriptions>
<TPA_Extensions>
<Description Name="First Description">
<Text>First line of first description.</Text>
<Text>Second line of first description.</Text>
</Description>
<Description>
<Text>Second description without name.</Text>
</Description>
</TPA_Extensions>
</HotelDescriptiveContent>
</HotelDescriptiveContents>
</OTA_HotelDescriptiveInfoRS>
</soap:Body>
</soap:Envelope>
Hotel Details displayed

Reservation


Request
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>testLogin123</userid>
<password>txxxxxxxxxxxx;</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_HotelResRQ xmlns="http://www.opentravel.org/OTA/2003/05"
EchoToken="6C85DDBD-EB62-444D-B2C3-F59BDF65BE98"
Version="6" PrimaryLangID="en" AltLangID="en">
<POS>
<Source ISOCurrency="USD"></Source>
</POS>
<HotelReservations>
<HotelReservation>
<RoomStays>
<RoomStay>
<RatePlans>
<RatePlan RatePlanID="XNFYP4I">
<Guarantee GuaranteeType="CC/DC/Voucher">
<GuaranteesAccepted>
<GuaranteeAccepted>
<PaymentCard CardCode="VI" ExpireDate="1220">
<CardType Code="VI">VISA</CardType>
<CardHolderName>HOTELSERVICEAMADEUS TESTUSERMOCK</CardHolderName>
</PaymentCard>
</GuaranteeAccepted>
</GuaranteesAccepted>
</Guarantee>
</RatePlan>
</RatePlans>
<TimeSpan Start="2018-02-12" End="2018-02-13"></TimeSpan>
<BasicPropertyInfo HotelCode="419430"></BasicPropertyInfo>
</RoomStay>
</RoomStays>
<ResGuests>
<ResGuest>
<Profiles>
<ProfileInfo>
<Profile>
<Customer Gender="Unknown">
<PersonName Language="en">
<GivenName>HOTELSERVICEAMADEUS</GivenName>
<Surname>TESTUSERMOCK</Surname>
</PersonName>
<Telephone PhoneNumber="3141011001"></Telephone>
<Email>hrs_hs2_amadeus_mock@concurautm3.com</Email>
<Address>
<AddressLine>123 Sesame St.</AddressLine>
<CityName>Alexandria</CityName>
<PostalCode>22314</PostalCode>
<StateProv></StateProv>
<CountryName Code="US">USA</CountryName>
</Address>
<CitizenCountryName Code="US"></CitizenCountryName>
</Customer>
<CompanyInfo>
<CompanyName>CONCURTECH</CompanyName>
</CompanyInfo>
</Profile>
</ProfileInfo>
</Profiles>
<GuestCounts>
<GuestCount Count="1"></GuestCount>
</GuestCounts>
</ResGuest>
</ResGuests>
</HotelReservation>
</HotelReservations>
</OTA_HotelResRQ>
</Body>
</Envelope>
Response
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_HotelResRS xmlns="http://www.opentravel.org/OTA/2003/05"
xmlns:ns2="http://www.concur.com/webservice/auth"
ResResponseType="Reserved">
<Success/>
<HotelReservations>
<HotelReservation>
<UniqueID ID="88618333"/>
<RoomStays>
<RoomStay>
<RatePlans>
<RatePlan RatePlanID="EZ57LL7">
<CancelPenalties CancelPolicyIndicator="true">
<CancelPenalty>
<PenaltyDescription>
<Text>test cancel policy 1</Text>
</PenaltyDescription>
</CancelPenalty>
<CancelPenalty>
<Deadline AbsoluteDeadline="2018-02-22T18:00"/>
</CancelPenalty>
</CancelPenalties>
</RatePlan>
</RatePlans>
<RoomRates>
<RoomRate>
<Rates>
<Rate RoomPricingType="Per stay">
<PaymentPolicies>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="VI"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="MC"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="CA"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="IK"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="AX"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
</PaymentPolicies>
<Total AmountAfterTax="85.00" AmountBeforeTax="85.00" CurrencyCode="EUR"/>
</Rate>
</Rates>
</RoomRate>
</RoomRates>
<TimeSpan End="2018-02-23" Start="2018-02-22"/>
<BasicPropertyInfo HotelCode="50709" HotelName="Alexander Plaza">
<Address>
<AddressLine>Rosenstr. 1</AddressLine>
<CityName>Berlin</CityName>
<CountryName Code="DEU">Federal Republic of Germany</CountryName>
<StateProv StateCode="BE">Berlin disctrict</StateProv>
<PostalCode>BE123</PostalCode>
</Address>
<ContactNumbers>
<ContactNumber PhoneNumber="3024001722"/>
</ContactNumbers>
</BasicPropertyInfo>
</RoomStay>
</RoomStays>
<ResGuests>
<ResGuest>
<Profiles>
<ProfileInfo>
<Profile>
<Customer>
<PersonName>
<GivenName>TESTER</GivenName>
<Surname>Testovic</Surname>
</PersonName>
</Customer>
</Profile>
</ProfileInfo>
</Profiles>
</ResGuest>
</ResGuests>
<ResGlobalInfo>
<Comments>
<Comment Name="Comment 1">
<Text>First line of Comment 1.</Text>
<Text>Second line of Comment 1.</Text>
</Comment>
<Comment>
<Text>First line of Comment 2 without name.</Text>
</Comment>
</Comments>
</ResGlobalInfo>
</HotelReservation>
</HotelReservations>
</OTA_HotelResRS>
</soap:Body>
</soap:Envelope>
Read

Request
<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>testLogin123</userid>
<password>txxxxxxxxxxxx;</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05"
EchoToken="4E1B8BF4-ACBD-4709-9FCC-B59EB2550086"
Version="5.002" PrimaryLangID="en" AltLangID="en">
<POS>
<Source ISOCurrency="USD"></Source>
</POS>
<UniqueID Type="14" ID="88618333"></UniqueID>
</OTA_ReadRQ>
</Body>
</Envelope>
Response
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_HotelResRS xmlns="http://www.opentravel.org/OTA/2003/05"
xmlns:ns2="http://www.concur.com/webservice/auth"
ResResponseType="Reserved">
<Success/>
<HotelReservations>
<HotelReservation>
<UniqueID ID="88621190"/>
<RoomStays>
<RoomStay>
<RatePlans>
<RatePlan RatePlanID="P4PGI5Q">
<CancelPenalties CancelPolicyIndicator="true">
<CancelPenalty>
<PenaltyDescription>
<Text>test cancel policy 1</Text>
</PenaltyDescription>
</CancelPenalty>
<CancelPenalty>
<PenaltyDescription>
<Text>test cancel policy 2</Text>
</PenaltyDescription>
<PenaltyDescription>
<Text>test cancel policy 3</Text>
</PenaltyDescription>
</CancelPenalty>
<CancelPenalty>
<Deadline AbsoluteDeadline="2018-02-22T18:00"/>
</CancelPenalty>
</CancelPenalties>
</RatePlan>
</RatePlans>
<RoomRates>
<RoomRate>
<Rates>
<Rate RoomPricingType="Per stay">
<PaymentPolicies>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="VI"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="MC"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="CA"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="IK"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
<GuaranteePayment>
<AcceptedPayments>
<AcceptedPayment>
<PaymentCard CardCode="AX"/>
</AcceptedPayment>
</AcceptedPayments>
</GuaranteePayment>
</PaymentPolicies>
<Total AmountAfterTax="208.95" AmountBeforeTax="208.95" CurrencyCode="EUR"/>
</Rate>
</Rates>
</RoomRate>
</RoomRates>
<TimeSpan End="2018-02-23" Start="2018-02-22"/>
<BasicPropertyInfo ChainCode="1609" HotelCode="10517" HotelName="Radisson Blu Hotel">
<Address>
<AddressLine>Karl-Liebknecht-Str. 3</AddressLine>
<CityName>Berlin</CityName>
<CountryName Code="DEU">Federal Republic of Germany</CountryName>
<StateProv StateCode="BE">Berlin disctrict</StateProv>
<PostalCode>BE123</PostalCode>
</Address>
<ContactNumbers>
<ContactNumber PhoneNumber="30238280"/>
</ContactNumbers>
</BasicPropertyInfo>
</RoomStay>
</RoomStays>
<ResGuests>
<ResGuest>
<Profiles>
<ProfileInfo>
<Profile>
<Customer>
<PersonName>
<GivenName>TESTER</GivenName>
<Surname>Testovic</Surname>
</PersonName>
</Customer>
</Profile>
</ProfileInfo>
</Profiles>
</ResGuest>
</ResGuests>
<ResGlobalInfo>
<Comments>
<Comment Name="Comment 1">
<Text>First line of Comment 1.</Text>
<Text>Second line of Comment 1.</Text>
</Comment>
<Comment>
<Text>First line of Comment 2 without name.</Text>
</Comment>
</Comments>
</ResGlobalInfo>
</HotelReservation>
</HotelReservations>
</OTA_HotelResRS>
</soap:Body>
</soap:Envelope>
Itinerary displayed

Cancel

Request
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<authentication xmlns="http://www.concur.com/webservice/auth">
<userid>testLogin123</userid>
<password>txxxxxxxxxxxx;</password>
</authentication>
</Header>
<Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<OTA_CancelRQ xmlns="http://www.opentravel.org/OTA/2003/05" CancelType="Cancel"
EchoToken="2186EB84-23D9-4977-B8A5-B5083C8DE228"
Version="3" PrimaryLangID="en" AltLangID="en">
<POS>
<Source ISOCurrency="USD"></Source>
</POS>
<UniqueID Type="14" ID="88618333"></UniqueID>
</OTA_CancelRQ>
</Body>
</Envelope>
Response
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<OTA_CancelRS xmlns="http://www.opentravel.org/OTA/2003/05"
xmlns:ns2="http://www.concur.com/webservice/auth"
Status="Cancelled">
<Success/>
<UniqueID ID="88618333" Type="14"/>
<UniqueID ID="27607" Type="15"/>
</OTA_CancelRS>
</soap:Body>
</soap:Envelope>

XSD schema
Current xsd schema for Hotel Service 2
Expense
Allocations
The SAP Concur Allocations API allows for the retrieval of allocation information as it relates to a Report ID, Entry ID, or Itemization ID. Using this API allows for an in-depth review of Expense Report Data and how that data has been allocated in SAP Concur. The Allocations API allows for the programmatic gathering of details on how the expense report data was allocated by the report owner, making it ideal for Data Gathering, Expense Reporting, and Validations.
Version
3.0
Retrieve All Allocations Per Entry or Report
GET /api/v3.0/expense/allocations
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
limit |
Int32 |
query |
The number of records to return. The default is 25 and the maximum is 100. |
offset |
string |
query |
The starting point of the next set of results, after the limit specified in the limit field has been reached. |
reportID |
string |
query |
The unique identifier for the report as it appears in the Concur Expense UI. Format: A variable-length string. Maximum length: 32 characters. |
entryID |
string |
query |
The unique identifier for the expense entry. |
itemizationID |
string |
query |
The unique identifier for the expense itemization. |
Note: userId is not a supported query string parameter for this API.
Request URL
https://www.concursolutions.com/api/v3.0/expense/allocations?limit=10
JSON Example of a Successful Response
{
"Items": [
{
"EntryID": "gWidFO7ikXSy7gHnNngC12jkL7khMiREv4g",
"Percentage": "100.00000000",
"IsPercentEdited": false,
"IsHidden": true,
"AccountCode1": "1",
"AccountCode2": null,
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"Custom6": null,
"Custom7": null,
"Custom8": null,
"Custom9": null,
"Custom10": null,
"Custom11": null,
"Custom12": null,
"Custom13": null,
"Custom14": null,
"Custom15": null,
"Custom16": null,
"Custom17": null,
"Custom18": null,
"Custom19": null,
"Custom20": null,
"ID": "gWmudeHM8AuFikny3Hrpz$s2gaNvc0E7Xfyw",
"URI": "https://www.concursolutions.com/api/v3.0/expense/allocations/gWmudeHM8AuFikny3Hrpz$s2gaNvc0E7Xfyw"
},
{
"EntryID": "gWidFO7ikXSy41$smPkwdC5cL1aku$pSgc$p4g",
"Percentage": "100.00000000",
"IsPercentEdited": false,
"IsHidden": true,
"AccountCode1": "1",
"AccountCode2": null,
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"Custom6": null,
"Custom7": null,
"Custom8": null,
"Custom9": null,
"Custom10": null,
"Custom11": null,
"Custom12": null,
"Custom13": null,
"Custom14": null,
"Custom15": null,
"Custom16": null,
"Custom17": null,
"Custom18": null,
"Custom19": null,
"Custom20": null,
"ID": "gWmudeHM8AuFhxez1E72ExJPksvTH0KPPyw",
"URI": "https://www.concursolutions.com/api/v3.0/expense/allocations/gWmudeHM8AuFhxez1E72ExJPksvTH0KPPyw"
}
]
}
Response
Retrieve a Single Allocation by ID
GET /api/v3.0/expense/allocations/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The unique identifier for the allocation. |
user |
string |
query |
The login ID of the user who owns the allocation. The user must have the Web Services Admin role to use this parameter. |
Allocations - Schema
Allocations
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Allocation |
The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
Allocation
| Name | Type | Format | Description |
|---|---|---|---|
AccountNumber |
string |
- | The primary accounting code assigned to the expense type associated with this allocation. Typically, expense types have only a primary account code. |
AccountCode2 |
string |
- | The secondary or alternative accounting code assigned to the expense type associated with this allocation. |
Custom1 through Custom20 |
CustomFieldExtension |
- | A custom field associated with the allocation. This field may or may not have data, depending on how Expense is configured. Format: Text field. Maximum length: 64 characters. |
EntryID |
string |
- | The unique identifier for the expense entry. |
ID |
string |
- | The unique identifier of the resource. |
IsHidden |
Boolean |
- | Indicates whether the allocation is hidden. Format: true or false |
IsPercentEdited |
Boolean |
- | Indicates whether the percentage has been edited. Format: true or false |
Percentage |
string |
- | The percentage of the expense that is included in this allocation. |
URI |
string |
- | The URI to the resource. |
Custom Field
| Name | Type | Format | Description |
|---|---|---|---|
Code |
string |
- | For list fields, this is the list item code. |
Label |
string |
- | The label value for the custom field. |
ListItemID |
string |
- | For list fields, this is the list item ID. |
Sequence |
integer |
- | The sequence value for this custom field i.e. the order in which this field appears on the form. |
Type |
string |
- | The custom field type. Possible values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text |
Value |
string |
- | The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters |
Request URL
https://www.concursolutions.com/api/v3.0/expense/allocations/gWmudeHM8AuFlD9Py%24p7cwkclNQvGC1JQPyw
JSON Example of a Successful Response
{
"EntryID": "gWidFO7ikXSy8HdaIfw32sJhcmk76TjD$p4g",
"Percentage": "100.00000000",
"IsPercentEdited": false,
"IsHidden": true,
"AccountCode1": "1",
"AccountCode2": null,
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"Custom6": null,
"Custom7": null,
"Custom8": null,
"Custom9": null,
"Custom10": null,
"Custom11": null,
"Custom12": null,
"Custom13": null,
"Custom14": null,
"Custom15": null,
"Custom16": null,
"Custom17": null,
"Custom18": null,
"Custom19": null,
"Custom20": null,
"ID": "gWmudeHM8AuFlD9Py$p7cwkclNQvGC1JQPyw",
"URI": "https://www.concursolutions.com/api/v3.0/expense/allocations/gWmudeHM8AuFlD9Py$p7cwkclNQvGC1JQPyw"
}
Attendee Types v3
The Attendee Type resource represents the type of attendee as configured in Concur.
- Retrieve all attendee types
- Retrieve attendee types by ID
- Create a new attendee type DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016
- Update existing attendee type
- Delete an attendee type DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016
- Schema
Version
3.0
Attendee Types v1 (Deprecated)
Retrieve all attendees types
GET /api/v3.0/expense/attendeetypes/
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
offset |
string |
query |
The starting point of the next set of results, after the limit specified in the limit field has been reached. |
limit |
Int32 |
query |
The number of records to return. Default value: 25 |
Request URL
https://www.concursolutions.com/api/v3.0/expense/attendeetypes?limit=10
JSON example of a successful response
{
"Items": [
{
"Name": "Business Guest",
"Code": "BUSGUEST",
"AttendeeFormID": "gWvidmKNPVEaOg$s66rqA62OJVXfvHBMs4sw",
"DuplicateSearchFields": [
"Title",
"Company",
"OwnerEmpName",
"FirstName",
"LastName"
],
"ConnectorID": "",
"AllowManuallyEnteredAttendees": true,
"AllowAttendeeCountEditing": true,
"ID": "gWjUHBxUY4iQLA9KTkbtUD6pc",
"URI": "https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjUHBxUY4iQLA9KTkbtUD6pc"
},
{
"Name": "Healthcare Professional",
"Code": "HCP",
"AttendeeFormID": "gWvidmKNPVEH7wO$pDpD9$pk6xVlyJ4EjwIdA",
"DuplicateSearchFields": [
"Title",
"Custom18",
"ExternalId",
"FirstName",
"LastName",
"Custom7",
"Custom14",
"Custom15",
"Custom16",
"Custom17",
"Custom19",
"Custom8",
"Custom20"
],
"ConnectorID": "",
"AllowManuallyEnteredAttendees": true,
"AllowAttendeeCountEditing": false,
"ID": "gWjYOjoOorT3dhpHGto5H$poJuoa0m",
"URI": "https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOjoOorT3dhpHGto5H$poJuoa0m"
}
]
}
Retrieve attendee types by ID
GET /api/v3.0/expense/attendeetypes/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the attendee type. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOjoOorT3dhpHGto5H%24poJuoa0m
JSON example of a successful response
{
"Name": "Healthcare Professional",
"Code": "HCP",
"AttendeeFormID": "gWvidmKNPVEH7wO$pDpD9$pk6xVlyJ4EjwIdA",
"DuplicateSearchFields": [
"Title",
"Custom18",
"ExternalId",
"FirstName",
"LastName",
"Custom7",
"Custom14",
"Custom15",
"Custom16",
"Custom17",
"Custom19",
"Custom8",
"Custom20"
],
"ConnectorID": "",
"AllowManuallyEnteredAttendees": true,
"AllowAttendeeCountEditing": false,
"ID": "gWjYOjoOorT3dhpHGto5H$poJuoa0m",
"URI": "https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOjoOorT3dhpHGto5H$poJuoa0m"
}
Create a new attendee type
DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016
POST /api/v3.0/expense/attendeetypes
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
content |
- | body |
Required The AttendeeType object to create. |
Input
Response
Request URL
https://www.concursolutions.com/api/v3.0/expense/attendeetypes
JSON example of a successful response
{
"ID": "gWjYOj4JuT5VB$paQnF31149$sKgaM$p",
"URI": "https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOj4JuT5VB$paQnF31149$sKgaM$p"
}
Update existing attendee type
PUT /api/v3.0/expense/attendeetypes/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the attendee type. |
content |
- | body |
Required The partial or complete Attendee object to update. |
Input
Response
Request URL
https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOjoa7Fe0HsTGEk417OCzqUf1A
Delete an attendee type
DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016
DELETE /api/v3.0/expense/attendeetypes{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the attendee type to delete |
Input
Response
Request URL
https://www.concursolutions.com/api/v3.0/expense/attendeetypes/gWjYOjomP3Jxp6dFC%24pIg%24sc99nQQ3q
Attendee Type - Schema
Attendee Type
| Name | Type | Format | Description |
|---|---|---|---|
AllowAttendeeCountEditing |
boolean |
- | Determines whether users are allowed to edit the count for this attendee type. Format: true or false |
AllowManuallyEnteredAttendees |
boolean |
- | Determines whether users are allowed to add attendees for this attendee type. Format: true or false |
AttendeeFormID |
string |
- | The unique identifier for the attendee form for this attendee type. |
Code |
string |
- | A code that indicates the type of attendee. Examples: EMPLOYEE, SPOUSE, BUSGUEST. Maximum length: 40 characters |
ConnectorID |
string |
- | The unique identifier for the Application Connector that is the data source for this attendee type. When this field is empty, the Expense database is the data source. |
DuplicateSearchFields |
Array |
AttendeeType | The list of Attendee field IDs used by the Add Attendee user interface to alert users that the attendee they want to add is a possible duplicate. This parent element has a DuplicateSearchField child element for each field ID. |
ID |
string |
- | The unique identifier of the resource. |
Name |
string |
- | The name for the attendee type. This name must be unique. Maximum length: 40 characters |
URI |
string |
- | The URI to the resource. |
Digital Tax Invoices
The Digital Tax Invoice web service allows digital tax invoice validators to view tax invoices and update them with a validation status. This web service currently supports the Comprobante Fiscal Digital (CFD) digital tax invoice format used in Mexico. Other countries may be supported in future releases.
- Retrieve All Digital Tax Invoices That Can Be Validated by the User Based On the Search Criteria
- Retrieve a Single Digital Tax Invoice by ID
- Update a Specified Digital Tax Invoice
- Schema
Version
3.0
Retrieve All Digital Tax Invoices That Can Be Validated by the User Based On the Search Criteria
GET /api/v3.0/expense/digitaltaxinvoices
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
offset |
query |
string |
The starting point of the next set of results, after the limit specified in the limit field has been reached. |
limit |
query |
Int32 |
The number of records to return. Default value: 25 |
modifiedafter |
query |
string |
A modification date for the queue record; this parameter can be used to limit the results of the GET request to the queue items that have been added since the last time the validation company queried the queue. The user must have the Web Services Admin role to use this parameter. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/digitaltaxinvoices?limit=5
Retrieve a Single Digital Tax Invoice by ID
GET /api/v3.0/expense/digitaltaxinvoices/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
path |
string |
Required The ID of the digital tax invoice. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/digitaltaxinvoices/gWj3IHRYiHZGRTDN6y4r4LN3phszY33HT%24pQ
Update a Specified Digital Tax Invoice
PUT /api/v3.0/expense/digitaltaxinvoices/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
content |
body |
- | Required A status update for the digital tax invoice. |
id |
path |
string |
Required The ID of the digital tax invoice to update. |
Digital Tax Invoices - Schema
Digital Tax Invoices
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Digital Tax Invoice | The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
Digital Tax Invoice
| Name | Type | Format | Description |
|---|---|---|---|
ConcurReceiptID |
string |
- | Required The ID of the digital tax invoice in plain text. |
ID |
string |
- | The unique identifier of the resource. |
URI |
string |
- | The URI to the resource. |
AccountID |
string |
- | Required The unique identifier assigned by the validation partner to the SAP Concur client company that owns the digital tax invoices. |
DocumentID |
string |
- | Required The ID of the report in plain text. |
ReceiptData |
string |
- | Required The digital tax invoice data. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/digitaltaxinvoices/gWj3IHRYiHZGUtIO83ILhbNHqCsjMmkvj%24pQ
Attendees v3
- Retrieve all attendees owned by the specified user
- Retrieve a single attendee by ID
- Create a new attendee
- Update existing attendees
- Schema
Related
Retrieve all attendees owned by the specified user
Request
URI
Template
GET /api/v3.0/expense/attendees
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
externalID |
string |
query |
The external ID of an attendee. By entering a value for this parameter, you can limit the results to the attendees who match the specified external ID. Up to 10 comma-separated external IDs may be specified. |
attendeeTypeID |
string |
query |
The ID of an attendee type. By entering a value for this parameter, you can limit the results to the attendees who match the specified type. |
offset |
string |
query |
The starting point of the next set of results, after the limit specified in the limit field has been reached. |
limit |
Int32 |
query |
The number of records to return. Default value: 25 |
user |
string |
query |
The login ID of the user that has added the attendee to an expense. The user who is performing this API request must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter |
Payload
None
Response
Payload
Example
Request
GET https://www.concursolutions.com/api/v3.0/expense/attendees?limit=15
Response
{
"Items": [
{
"AttendeeTypeCode": "NOSHOWS",
"AttendeeTypeID": "gWjYOjoCmOo2Ua$pH4qnCsQxgS8Z0E",
"FirstName": null,
"LastName": "No Show Attendee",
"MiddleInitial": null,
"Suffix": null,
"Company": null,
"Title": null,
"ExternalID": null,
"HasExceptionsPrevYear": false,
"HasExceptionsYTD": false,
"TotalAmountPrevYear": 0,
"TotalAmountYTD": 0,
"VersionNumber": 1,
"OwnerName": "System, Concur",
"OwnerLoginID": "ConcurSystem",
"CurrencyCode": "USD",
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"Custom6": null,
"Custom7": null,
"Custom8": null,
"Custom9": null,
"Custom10": null,
"Custom11": null,
"Custom12": null,
"Custom13": null,
"Custom14": null,
"Custom15": null,
"Custom16": null,
"Custom17": null,
"Custom18": null,
"Custom19": null,
"Custom20": null,
"Custom21": null,
"Custom22": null,
"Custom23": null,
"Custom24": null,
"Custom25": null,
"ID": "gWj3IHRYiHZGUtIO83ILhbNHqCsjMmkvj$pQ",
"URI": "https://www.concursolutions.com/api/v3.0/expense/attendees/gWj3IHRYiHZGUtIO83ILhbNHqCsjMmkvj$pQ"
}
]
}
Retrieve a single attendee by ID
Request
URI
Template
/api/v3.0/expense/attendees/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The attendee object to create. |
user |
string |
query |
The login ID of the user that has added the attendee to an expense. The user who is performing this API request must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter |
Payload
None
Response
Payload
Example
GET https://www.concursolutions.com/api/v3.0/expense/attendees/gWj3IHRYiHZGd0HJy%24p5Uk0zITlsMX0ymT%24pA
Request
Response
{
"AttendeeTypeCode": "PRIVATE",
"AttendeeTypeID": "gWjYOjoa7Fe0HsTGEk417OCzqUf1A",
"FirstName": "Diego",
"LastName": "Rodriguez",
"MiddleInitial": null,
"Suffix": null,
"Company": "Contoso",
"Title": null,
"ExternalID": "1",
"HasExceptionsPrevYear": false,
"HasExceptionsYTD": false,
"TotalAmountPrevYear": 0,
"TotalAmountYTD": 0,
"VersionNumber": 1,
"OwnerName": "System, Concur",
"OwnerLoginID": "ConcurSystem",
"CurrencyCode": "USD",
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"Custom6": null,
"Custom7": null,
"Custom8": null,
"Custom9": null,
"Custom10": null,
"Custom11": null,
"Custom12": null,
"Custom13": null,
"Custom14": null,
"Custom15": null,
"Custom16": null,
"Custom17": null,
"Custom18": null,
"Custom19": null,
"Custom20": null,
"Custom21": null,
"Custom22": null,
"Custom23": null,
"Custom24": null,
"Custom25": null,
"ID": "gWj3IHRYiHZGd0HJy$p5Uk0zITlsMX0ymT$pA",
"URI": "https://www.concursolutions.com/api/v3.0/expense/attendees/gWj3IHRYiHZGd0HJy$p5Uk0zITlsMX0ymT$pA"
}
Create a new attendee
Request
URI
/api/v3.0/expense/attendees
Template
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
user |
string |
query |
The login ID of the user that has added the attendee to an expense. The user who is performing this API request must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter |
Payload
Response
Payload
Example
POST https://www.concursolutions.com/api/v3.0/expense/attendees
Request
Response
{
"ID": "gWj3IHRYiHZOQ2T9NNdJ$plN$s7$sG8LhZwjoQ",
"URI": "https://www.concursolutions.com/api/v3.0/expense/attendees/gWj3IHRYiHZOQ2T9NNdJ$plN$s7$sG8LhZwjoQ"
}
Update existing attendees
Request
URI
Template
/api/v3.0/expense/attendees/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The attendee ID |
user |
string |
query |
The login ID of the user that has added the attendee to an expense. The user who is performing this API request must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter |
Payload
Response
Payload
Example
PUT https://www.concursolutions.com/api/v3.0/expense/attendees/gWj3IHRYiHZOQ2T9NNdJ%24plN%24s7%24sG8LhZwjoQ
Request
- Showing developers exactly what they can expect in request and response values when using is perhaps the simplest way to complete this portion of the documentation.
- Use triple backticks to create fenced code blocks and a language identifier for syntax highlighting.
- See Creating and highlighting code blocks
Response
ToDo
Attendees v3 - Schema
Attendees
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Attendee |
The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
Attendee
| Name | Type | Format | Description |
|---|---|---|---|
AttendeeTypeCode |
string |
- | A code that indicates the type of attendee. Examples: EMPLOYEE, SPOUSE, BUSGUEST. Maximum length: 40 characters |
AttendeeTypeID |
string |
- | The ID of the attendee type. To obtain the attendee type ID value, use the GET /expense/attendeetypes endpoint. The value of the ID element in the response is the attendee type ID. |
Company |
string |
- | The name of the attendee's company. Maximum length: 150 characters |
CurrencyCode |
string |
- | The 3-letter ISO 4217 currency code for monetary amounts related to an attendee. |
Custom1 through Custom25 |
CustomField |
- | A custom field associated with the attendee. This field may or may not have data, depending on how Expense is configured. |
ExternalID |
string |
- | A unique identifier for the attendee, assigned outside of Concur. Maximum length: 48 characters NOTE: For HCP connectors where information returned to Concur represents one record per attendee+address pair, this value should be a unique identifier for that pair, and the unique identifier for the individual should be placed into a custom field. |
FirstName |
string |
- | The attendee's first name. Maximum length: 50 characters |
HasExceptionsPrevYear |
Boolean |
- | Determines whether the attendee had exceptions in the previous year, based on yearly total limits for attendees. Format: true or false |
HasExceptionsYTD |
Boolean |
- | Determines whether the attendee has exceptions in the current year, based on yearly total limits for attendees. Format: true or false |
ID |
string |
- | The unique identifier of the resource. |
LastName |
string |
- | The attendee's last name. Maximum length: 132 characters |
MiddleInitial |
string |
- | The attendee's middle initial. Maximum length: 1 character |
OwnerLoginID |
string |
- | The login ID of the user who owns the attendee record. |
OwnerName |
string |
- | The name of the user who owns the attendee record. |
Suffix |
string |
- | The attendee's name suffix. Maximum length: 32 characters |
Title |
string |
- | The attendee's title. Maximum length: 32 characters |
TotalAmountPrevYear |
Decimal |
- | The total amount spent on the attendee in the previous calendar year. |
TotalAmountYTD |
Decimal |
- | The total amount spent on the attendee in the current calendar year. |
URI |
string |
- | The URI to the resource. |
VersionNumber |
Int32 |
- | The attendee's version number. |
Custom Field
| Name | Type | Format | Description |
|---|---|---|---|
Code |
string |
- | For list fields, this is the list item code. |
ListItemID |
string |
- | For list fields, this is the list item ID. |
Type |
string |
- | The custom field type. Possible values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text |
Value |
string |
- | The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters |
Company Card Transactions
The corporate or credit card charges that are available for use in expense reports for the OAuth consumer.
Retrieves a list of unassigned company card charges for the user specified in the OAuth access token.
Version
1.1
URI
https://www.concursolutions.com/api/expense/expensereport/v1.1/CardCharges
Operations
Company Card Transaction - Request
Request Parameters
None.
Content Types
application/xml
Authorization Header
Authorization header with OAuth token for valid SAP Concur user. Required.
Company Card Transaction - Response
Content Types
application/xml
Company Card Transaction - Schema
This request will return a CardCharges parent element with a CardCharge child element for each transaction.
CardCharge Child Elements
| Element | Description |
|---|---|
| CardNumber | The number of the card, with all digits obscured OTHER than last 4 digits. |
| ExpKey | The code for the expense type of the transaction |
| Merchant | The merchant name for the transaction. |
| ExpName | The name of the expense type of the transaction. |
| TransactionAmount | The amount of the card transaction. |
| TransactionCrnCode | The currency code of the transaction amount. |
| TransactionDate | The date of the transaction. |
Company Card Transaction - Examples
XML Example Request
GET https://www.concursolutions.com/api/expense/expensereport/v1.1/CardCharges/ HTTP/1.1
Authorization: OAuth {access token}
...
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
<CardCharges
xmlns="https://www.concursolutions.com/api/expense/expensereport/2011/03">
<CardCharge>
<CardNumber>XXXXXXXXX1111</CardNumber>
<ExpKey>CARRT</ExpKey>
<ExpName>Car Rental</ExpName>
<Merchant>Hertz</Merchant>
<TransactionAmount>283.88000000</TransactionAmount>
<TransactionCrnCode>USD</TransactionCrnCode>
<TransactionDate>2010-08-19T00:00:00</TransactionDate>
</CardCharge>
<CardCharge>
<CardNumber>XXXXXXXXX1111</CardNumber>
<ExpKey>UNDEF</ExpKey>
<ExpName>Undefined</ExpName>
<Merchant>King Tires</Merchant>
<TransactionAmount>274.13000000</TransactionAmount>
<TransactionCrnCode>USD</TransactionCrnCode>
<TransactionDate>2010-08-19T00:00:00</TransactionDate>
</CardCharge>
</CardCharges>
Expense Delegators
Users that have granted delegate permissions to the another Expense user.
Retrieves the list of users that have granted delegate permissions to the user specified in the OAuth access token.
Version
1.1
URI
https://www.concursolutions.com/api/expense/expensereport/v1.1/Delegators
Operations
Expense Delegators - Request
Request Parameters
None.
Headers
Authorization Header
Authorization header with OAuth token for valid SAP Concur user. Required.
Accept Header
application/xml
Expense Delegators- Response
Content Types
application/xml
Expense Delegators - Schema
This request will return a DelegatorsList parent element with a Delegator parent element for each user that has granted delegate rights to the OAuth consumer.
Delegator Elements
| Element | Description |
|---|---|
| CanApprove | Whether the delegate is granted the right to approve expense reports on behalf of the delegator. |
| CanPrepare | Whether the delegate is granted the right to create expense reports on behalf of the delegator. |
| CanSubmit | Whether the delegate is granted the right to submit expense reports on behalf of the delegator. |
| CanTemporaryApprove | Whether the delegate is granted the same temporary approval rights as the delegator. |
| CanViewReceipts | Whether the delegate is granted the right to view receipts on behalf of the delegator. |
| ReceiveApprovalEmails | Whether the delegate also receives the approval emails sent to the delegator. |
| ReceivesEmails | Whether the delegate also receives the SAP Concur emails sent to the delegator. |
| DelegatorXUserID | The user ID of the delegator. |
Expense Delegators - Examples
XML Example Request
GET https://www.concursolutions.com/api/expense/expensereport/v1.1/Delegators HTTP/1.1
Authorization: OAuth {access token}
...
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
<DelegatorsList xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Delegator>
<CanApprove>N</CanApprove>
<CanPrepare>Y</CanPrepare>
<CanSubmit>Y</CanSubmit>
<CanTemporaryApprove>N</CanTemporaryApprove>
<CanViewReceipts>Y</CanViewReceipts>
<ReceiveApprovalEmails>N</ReceiveApprovalEmails>
<ReceivesEmails>N</ReceivesEmails>
<DelegatorXUserID>terryb@example.com</DelegatorXUserID>
</Delegator>
<Delegator>
<CanApprove>N</CanApprove>
<CanPrepare>Y</CanPrepare>
<CanSubmit>Y</CanSubmit>
<CanTemporaryApprove>N</CanTemporaryApprove>
<CanViewReceipts>N</CanViewReceipts>
<ReceiveApprovalEmails>N</ReceiveApprovalEmails>
<ReceivesEmails>N</ReceivesEmails>
<DelegatorXUserID>patd@example.com</DelegatorXUserID>
</Delegator>
</DelegatorsList>
Expense Entry Attendee v3
- Retrieve All Entry-Attendee Associations Owned by the User
- Retrieve an Entry-Attendee Association by ID
- Create a New Entry-Attendee Association
- Update a Specified Entry-Attendee Association
- Delete a Specified Entry-Attendee Association
- Schema
Prior Versions
2.0 documentation is available here.
Retrieve All Entry-Attendee Associations Owned by the User
GET /api/v3.0/expense/entryattendeeassociations
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
entryID |
string |
query |
The ID of the entry for which to retrieve entry-attendee associations. |
offset |
string |
query |
The starting point of the next set of results, after the limit specified in the limit field has been reached. |
limit |
Int32 |
query |
The number of records to return. Default value: 25 |
user |
string |
query |
The login ID of the user who owns this entry-attendee association. The user must have the Web Services Admin role to use this parameter. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations?limit=15&user=ALL
JSON Example of a Successful Response
{
"Items": [
{
"EntryID": "gWidFO7ikXS264Tf3Z68NmcXdkxhcxezfzA",
"AttendeeID": "gWj3IHRYiHZGX4xP$s0YUWUyoUjss$pWV3z$pQ",
"Amount": 80,
"AssociatedAttendeeCount": 1,
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"ID": "gWgSNsCedFvv8LE1LrkughW9mAyCN",
"URI": "https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgSNsCedFvv8LE1LrkughW9mAyCN"
},
{
"EntryID": "gWidFO7ikXSi7DX4hlLTggJD76w1IvtEvWw",
"AttendeeID": "gWj3IHRYiHZGSG6M4xo0PEyYXAs8rHGfD$pQ",
"Amount": 120,
"AssociatedAttendeeCount": 1,
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"ID": "gWgOOsCJrozFymvWtfB5Ri1WD$ste9",
"URI": "https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgOOsCJrozFymvWtfB5Ri1WD$ste9"
}
]
}
Retrieve an Entry-Attendee Association by ID
GET /api/v3.0/expense/entryattendeeassociations/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the entry-attendee association. |
user |
string |
query |
The login ID of the user who owns this entry-attendee association. The user must have the Web Services Admin role to use this parameter. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgSM%24s2kvfcQ8xC%24p6uaPsY6V6qB7FqOU
JSON Example of a Successful Response
{
"EntryID": "gWidFO7ikXV67u6QrT2w1Yhqzh4a8j$pEjCg",
"AttendeeID": "gWj3IHRYiHZOTjq8PONWIqyRFfGz4RoozoQ",
"Amount": 17.01,
"AssociatedAttendeeCount": 1,
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"ID": "gWgSM$s2kvfcQ8xC$p6uaPsY6V6qB7FqOU",
"URI": "https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgSM$s2kvfcQ8xC$p6uaPsY6V6qB7FqOU"
}
Create a New Entry-Attendee Association
POST /api/v3.0/expense/entryattendeeassociations
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
content |
- | body |
Required The EntryAttendeeAssociation object to create. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations
JSON Example of a Successful Response
{
"ID": "gWgSM$s2kvfcQ8xC$p6uaPsY6V6qB7FqOU",
"URI": "https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgSM$s2kvfcQ8xC$p6uaPsY6V6qB7FqOU"
}
Update a Specified Entry-Attendee Association
PUT /api/v3.0/expense/entryattendeeassociations/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the entry-attendee association. |
content |
- | body |
Required The partial or complete EntryAttendeeAssociation object to update. |
Delete a Specified Entry-Attendee Association
DELETE /api/v3.0/expense/entryattendeeassociations/{id}
Request URL
https://www.concursolutions.com/api/v3.0/expense/entryattendeeassociations/gWgSM%24s2kvfcQ8xC%24p6uaPsY6V6qB7FqOU
JSON Example of a Successful Response
no content
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The connection request ID. |
Expense Entry Attendee - Schema
Entry Attendee Associations
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Entry Attendee Association | The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
Entry Attendee Association
| Name | Type | Format | Description |
|---|---|---|---|
Amount |
Decimal |
- | The portion of the entry transaction amount assigned to this attendee. |
AssociatedAttendeeCount |
Int32 |
- | The count of additional attendees associated with this attendee. A count greater than 1 means there are unnamed attendees associated with this attendee. |
AttendeeID |
string |
- | The unique identifier of the associated attendee. To obtain the attendee ID value, use the GET /expense/attendees endpoint. The value of the ID element in the response is the attendee ID. |
Custom1 through Custom5 |
string |
- | The details from the Custom fields. These fields may not have data, depending on the configuration. |
EntryID |
string |
- | The unique identifier of the associated entry. To obtain the attendee ID value, use the GET /expense/entries endpoint. The value of the ID element in the response is the entry ID. |
ID |
string |
- | The unique identifier of the resource. |
URI |
string |
- | The URI to the resource. |
Entries
- Retrieve All Expense Entries
- Create a New Expense Entry
- Update an Expense Entry
- Delete an Expense Entry
- Schema
The SAP Concur Expense Entries API is used to manage expense reports and their entries in SAP Concur. It allows for the synchronizing and reconciliation of expense related information with your internal systems and reporting modules.
1.1 documentation is available here.
Retrieve All Expense Entries
Version 2.0, covers a wider range of partner scenarios and is recommended as the first step. However, depending on the entries you need to retrieve, using a combination of version 2.0 and version 3.0 should be considered. To see examples, review the VAT Reclaim integration guide.
Create a New Expense Entry
POST /api/v3.0/expense/entries
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
content |
body |
- | Required The expense entry object to create. |
user |
string |
query |
The login ID of the user who owns the entries. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/entries
JSON Example of a Successful Response
{
"ID": "gWidFO7ikXV647DRpQmvCXeFNA4VPTOczCg",
"URI": "https://www.concursolutions.com/api/v3.0/expense/entries/gWidFO7ikXV647DRpQmvCXeFNA4VPTOczCg"
}
Updates an Expense Entry
PUT /api/v3.0/expense/entries/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The expense entry ID. |
content |
body |
- | Required The partial or complete expense entry object to update. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/entries/gWidFO7ikXV66iSvqtG6Yd0wZ%24s4ftzvzTCg
Delete an Expense Entry
DELETE /api/v3.0/expense/entries/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the expense entry to delete. |
user |
string |
query |
The login ID of the user who owns the entries. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/entries/gWidFO7ikXV66iSvqtG6Yd0wZ%24s4ftzvzTCg
Schema
Entries
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Entry | The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
Entry
| Name | Type | Format | Description |
|---|---|---|---|
AllocationType |
string |
- | The type of allocations for the expense. Supported values: P - partial allocation, F - full allocation, N - no allocation. Use the GET /expense/allocations function to get information about this entry's allocations. |
ApprovedAmount |
decimal |
- | The approved amount of the expense entry, in the report currency. |
CompanyCardTransactionID |
string |
- | The unique identifier for a company card transaction that is associated with this expense. Concur Expense uses the Credit Card Import job to import company card transactions. Use the GET CompanyCardTransactions function to get information about these card transactions. This element is null when there is no company card transaction associated with this expense. |
Custom1 through Custom40 |
customField |
- | The details from the Custom fields. These fields may not have data, depending on the configuration. |
Comment |
string |
- | A comment that describes the expense entry. Maximum length: 500 characters |
Description |
string |
- | The description of the expense. Maximum length: 64 characters |
ElectronicReceiptID |
string |
- | The unique identifier for an eReceipt that is associated with this expense. Use the GET eReceipts function to get information about this eReceipt. This element is null when there is no eReceipt associated with this expense. |
EmployeeBankAccountID |
string |
- | The unique identifier of an employee bank account that is associated with this expense. Typically, this element is used when Expense Pay reimburses the employee for this expense. Use the GET BankAccounts function to get information about this bank account. |
ExchangeRate |
decimal |
- | The currency conversion rate that converts the transaction amount that is in the transaction currency into the posted amount that is in the report currency. This element is typically not provided. If this element is empty for transactions in a currency different than the user's reimbursement currency, Expense will use the company's configured exchange rates to determine the posted amount for the transaction. If the system is not able to determine the exchange rate, a value of 1.0 will be used. |
ExpenseTypeCode |
string |
- | Required The code for the expense type. Use GET /expense/expensegroupconfigurations to learn the expense type code for expense types that are active for this report's policy. |
ExpenseTypeName |
string |
- | The name of the expense type, localized to the user's language. |
FormID |
string |
- | The ID of the form used by this expense entry. |
HasAppliedCashAdvance |
boolean |
true / false |
Whether the entry has a cash advance applied to it. |
HasAttendees |
boolean |
true / false |
Indicates whether the expense has attendees. Use the GET /expense/entryattendeeassociations function to get information about this entry's attendees. |
HasComments |
boolean |
true / false |
Whether or not the expense entry has comments. |
HasExceptions |
boolean |
true / false |
Whether the expense has exceptions. Use the GET ExpenseEntryExceptions function to get information about this entry's exceptions. |
HasImage |
boolean |
true / false |
Indicates whether there is an entry image attached to the entry. Use the GET Entry Images function to get this entry image. |
HasItemizations |
boolean |
true / false |
Indicates whether the expense has itemizations. Use the GET /expense/itemizations function to get information about this entry's itemizations. |
HasVAT |
boolean |
true / false |
Indicates whether the entry has VAT data. |
ID |
string |
- | The unique identifier of the resource. |
IsBillable |
boolean |
true / false |
Indicates whether the expense is billable. |
IsImageRequired |
boolean |
true / false |
Indicates whether an entry image is required for the entry. |
IsPaidByExpensePay |
boolean |
true / false |
Whether the entry is paid using the Expense Pay service. This element has a value if the report has reached the Processing Payment workflow step, because this is when Concur Expense determines whether it will be paid by Expense Pay. |
IsPersonal |
boolean |
true / false |
Indicates whether the expense is personal (that is, non-reimbursable). |
IsPersonalCardCharge |
boolean |
true / false |
Indicates whether the expense entry was imported from a personal card feed. Concur Expense uses the Yodlee API to import these card transactions. |
Journey |
journey |
- | Journey data. This element is used when the entry is a mileage expense. For expense types with an expense code that is either Company Car or Personal Car, the Journey child element is required. This element should not be used for expense types with an expense code that is neither Company Car nor Personal Car. |
LastModified |
dateTime |
- | The UTC date when the entry was last modified. |
LocationCountry |
string |
- | The 2-letter ISO 3166-1 country code where the expense was incurred. |
LocationID |
string |
- | The unique identifier for the location where the expense was incurred. Use the GET /common/locations function to get information for this location. |
LocationName |
string |
- | The location where the expense was incurred, usually the city name. |
LocationSubdivision |
string |
- | The ISO 3166-2:2007 country subdivision state, province, or other country subdivision where the expense was incurred. |
OrgUnit1 through OrgUnit6 |
customField |
- | The details from the Org Unit fields. These fields may not have data, depending on the configuration. |
PaymentTypeID |
string |
- | Required The ID of the payment type for the entry. Use GET /expense/expensegroupconfigurations to learn the payment type ID for payment types that are active for this report's expense group. For mileage expenses, use the Cash payment type. For expense types with an expense code that uses a transaction amount instead of a distance, this element is required. This element should not be used for expense types with an expense code for Company Car or Personal Car, because these two expense codes always use the Cash payment type. |
PaymentTypeName |
string |
- | The name of the payment type, localized to the user's language. |
PostedAmount |
decimal |
- | The amount of the expense entry, in the report currency. |
ReceiptReceived |
boolean |
true / false |
Indicates whether this entry has been reviewed by a processor. Format: true or false |
ReportID |
string |
- | Required The report ID of the report where the entry will be added. |
ReportOwnerID |
string |
- | The login ID of the report owner. Use the GET User Information function to learn details about this user. |
SpendCategoryCode |
string |
- | The ID of the spending category that is specified for this expense entry. |
SpendCategoryName |
string |
- | The name of the spending category that is specified for this expense entry, localized to the user's language. |
TaxReceiptType |
string |
- | The receipt type for this entry. Supported values: T - tax receipt, R - regular receipt, N - no receipt |
TransactionAmount |
decimal |
- | Required The amount of the expense entry, in the transaction currency paid to the vendor. |
TransactionCurrencyCode |
string |
- | Required The 3-letter ISO 4217 currency code for the expense entry transaction amount. This is the currency in which the vendor was paid. For expense types with an expense code that uses a transaction amount instead of a distance, this element is required. This element should not be used for expense types with an expense code for Company Car or Personal Car, because for these two expense codes the currency is always the Report Currency. |
TransactionDate |
dateTime |
YYYY-MM-DD |
Required The date when the good or service associated with this expense entry was provided. |
TripID |
string |
- | The unique identifier of a trip in the Itinerary Service that includes a travel booking associated with this expense. Use GET ItineraryDetails to get information about this trip and the travel booking. This element is null when there is no trip associated with the expense. |
URI |
string |
- | The URI to the resource. |
VendorDescription |
string |
- | The name of the vendor for the expense entry. Maximum length: 64 characters |
VendorListItemID |
string |
- | The unique identifier for a vendor list item. Use the GET /common/lists function to get information about this list item. |
VendorListItemName |
string |
- | The name of an item from a vendor list. |
CustomField
| Name | Type | Format | Description |
|---|---|---|---|
Code |
string |
- | For list fields, this is the list item code. |
ListItemID |
string |
- | For list fields, this is the list item ID. |
Type |
string |
- | The custom field type. Supported values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text |
Value |
string |
- | The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters |
Journey
| Name | Type | Format | Description |
|---|---|---|---|
BusinessDistance |
Int32 |
- | The portion of the journey for business use, in the report owner's unit of measure for distances. This element is required in order to post a personal car mileage expense entry, or to post a company car mileage expense when there is no PersonalDistance value. When using the Odometer elements, the sum of PersonalDistance and BusinessDistance must equal the difference between OdometerEnd and OdometerStart. |
EndLocation |
string |
- | Required Indicates where the journey ended. This is also known as the "To Location". Maximum length: 100 characters |
NumberOfPassengers |
Int32 |
- | The number of people in the vehicle during the journey. Used with Variable-Rate, Personal or Company Car. |
OdometerEnd |
Int32 |
- | The odometer reading at the end of the journey. The value must be greater than the OdometerStart value. This element is used with Variable-Rate and Company Car configuration types. |
OdometerStart |
Int32 |
- | The odometer reading at the start of the journey. This element is used with Variable-Rate and Company Car configuration types. |
PersonalDistance |
Int32 |
- | The portion of the journey for personal use. This element is required in order to post a company car mileage expense when there is no BusinessDistance value. When using the Odometer elements, the sum of PersonalDistance and BusinessDistance must equal the difference between OdometerEnd and OdometerStart. Used with Company Car configuration types. |
StartLocation |
string |
- | Required Indicates where the journey started. This is also known as the "From Location". Maximum length: 100 characters |
UnitOfMeasure |
string |
- | Required The unit of measure for distance and odometer values. Supported values: M - miles, K - kilometers |
NOTE: Clients that have Car Configurations that include variable rates or custom mileage expense type codes are not supported. We only support Car Configurations that include Personal Car One-Rate definitions, using the default mileage expense type code (MILEG) where Google Maps is not set as mandatory.
Expense Form Field
The configured fields for the specified expense form.
Version
1.1
URI
https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Form/_{FormId}_/Fields
Operations
Get a List of Form Fields
Retrieves the details of the configured form fields for the specified form.
NOTE: When sending in requests using these fields, be sure to include the required fields from the form and any additional required fields specified in the request documentation.
Expense Form Field - Request
Request Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
| {FormId}/Fields | required | The unique identifier for the desired form and the Fields keyword. |
Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Form/{FormId}/Fields
URI Source: The FormId is returned in the FormId element by the Get Form Data function.
Headers
Authorization Header
Authorization header with OAuth token for valid SAP Concur user. Required.
Accept Header
application/xml
Expense Form Field - Response
Expense Form Field - Response Schema
This request will return a FormFieldsList parent element with a FormField parent element for each configured form field.
FormField Elements
| Element | Description |
|---|---|
| Id | The form field ID. |
| Label | The form field label. |
| ControlType | The type of field. |
| DataType | The type of data accepted by the field. |
| MaxLength | The maximum length of the field value. |
| Required | Whether the field is required. |
| Cols | The number of columns the field contains. |
| Access | The access level the specified user has to the field. |
| Width | The width of the field. |
| Custom | Whether the field is custom. |
| Sequence | The field order on the form. |
XML Example Request
GET https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Form/nAaT8$puKKO2$pEVlsXfSruLpDfZL0wVM$s7/Fields HTTP/1.1
Authorization: OAuth {access token}
...
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
<FormFieldsList xmlns="https://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<FormField>
<Id>Name</Id>
<Label>ReportName</Label>
<ControlType>edit</ControlType>
<DataType>VARCHAR</DataType>
<MaxLength>32</MaxLength>
<Required>Y</Required>
<Cols>32</Cols>
<Access>RW</Access>
<Width>32</Width>
<Custom>N</Custom>
<Sequence>1</Sequence>
</FormField>
<FormField>
<Id>ReportId</Id>
<Label>ReportID</Label>
<ControlType>static</ControlType>
<DataType>VARCHAR</DataType>
<MaxLength>32</MaxLength>
<Required>Y</Required>
<Cols />
<Access>RO</Access>
<Width />
<Custom>N</Custom>
<Sequence>2</Sequence>
</FormField>
<FormField>
<Id>PolKey</Id>
<Label>Policy</Label>
<ControlType>picklist</ControlType>
<DataType>INTEGER</DataType>
<MaxLength />
<Required>Y</Required>
<Cols />
<Access>RW</Access>
<Width />
<Custom>N</Custom>
<Sequence>3</Sequence>
</FormField>
<FormField>
<Id>EmpName</Id>
<Label>EmployeeName</Label>
<ControlType>static</ControlType>
<DataType>VARCHAR</DataType>
<MaxLength>32</MaxLength>
<Required>Y</Required>
<Cols />
<Access>HD</Access>
<Width />
<Custom>N</Custom>
<Sequence>4</Sequence>
</FormField>
<FormField>
<Id>UserDefinedDate</Id>
<Label>ReportDate</Label>
<ControlType>edit</ControlType>
<DataType>TIMESTAMP</DataType>
<MaxLength />
<Required>N</Required>
<Cols />
<Access>RW</Access>
<Width />
<Custom>N</Custom>
<Sequence>5</Sequence>
</FormField>
<FormField>
<Id>Purpose</Id>
<Label>BusinessPurpose</Label>
<ControlType>textarea</ControlType>
<DataType>VARCHAR</DataType>
<MaxLength>500</MaxLength>
<Required>Y</Required>
<Cols>32</Cols>
<Access>RW</Access>
<Width>32</Width>
<Custom>N</Custom>
<Sequence>6</Sequence>
</FormField>
</FormFieldsList>
Expense Form
The configured expense forms in SAP Concur. Clients can have multiple forms configured for each form type.
Version
1.1
URI
https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Forms/
Operations
Get Form Types
Retrieves the list of configured form types.
Request
Request Parameters
None.
Headers
Authorization Header
Authorization header with OAuth token for valid SAP Concur user. Required.
Accept Header
application/xml
Response
Get Form Types Schema
This request will return a FormTypesList parent element with a FormType parent element for each configured form.
FormType Elements
| Element | Description |
|---|---|
| Name | The form type name. |
| FormCode | The form type code. |
Examples
XML Example Request
GET https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Forms HTTP/1.1
Authorization: OAuth {access token}
...
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
<FormTypesList
xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<FormType>
<Name>Expense Entry</Name>
<FormCode>ENTRYINFO</FormCode>
</FormType>
<FormType>
<Name>Expense Report Header</Name>
<FormCode>RPTINFO</FormCode>
</FormType>
<FormType>
<Name>Expense Allocation</Name>
<FormCode>ALLOCINFO</FormCode>
</FormType>
<FormType>
<Name>Expense Attendee</Name>
<FormCode>ATTNINFO</FormCode>
</FormType>
<FormType>
<Name>Authorization Request Expense Category</Name>
<FormCode>TRAVELREQENTRYINFO</FormCode>
</FormType>
<FormType>
<Name>Authorization Request Header</Name>
<FormCode>TRAVELREQINFO</FormCode>
</FormType>
<FormType>
<Name>Expense Detail View</Name>
<FormCode>EXPLISTDTL</FormCode>
</FormType>
<FormType>
<Name>Attendee Detail View</Name>
<FormCode>ATNLISTDTL</FormCode>
</FormType>
<FormType>
<Name>Expense Car</Name>
<FormCode>CARINFO</FormCode>
</FormType>
</FormTypesList>
Get Form Data
Retrieves the list of configured forms for the specified form type.
Request
Request Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
| FormCode | required | The identifier for the desired form. |
Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Forms/{FormCode}
URI Source: The FormCode is returned in the FormCode element in the Get Form Types response.
Headers
Authorization Header
Authorization header with OAuth token for valid SAP Concur user.
Accept Header
application/xml
Response
Get Form Data Schema
This request will return a FormDataList parent element with a FormData parent element for each configured form.
FormData Elements
| Element | Description |
|---|---|
| Name | The form name. |
| FormId | The form identifier. |
Examples
XML Example Request
GET https://www.concursolutions.com/api/expense/expensereport/v1.1/report/Forms/RPTINFO HTTP/1.1
Authorization: OAuth {access token}
...
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
<FormDataList xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<FormData>
<Name>Central Reconciliation Columns</Name>
<FormId>nAaT8$puKKOG5E4R9gCMyXVrFjo9NIbmQl</FormId>
</FormData>
<FormData>
<Name>Central Reconciliation Report</Name>
<FormId>nAaT8$puKKOGmK3xvAdnAOgJ9fxaoXjyW$s</FormId>
</FormData>
<FormData>
<Name>Default Report Information</Name>
<FormId>nAaT8$puKKO2$pEVlsXfSruLpDfZL0wVM$s7</FormId>
</FormData>
</FormDataList>
Expense Group Configurations
Retrieves the list of Expense Polices, Expense Types and Payment Types for the Expense Group the user specified in the OAuth access token is assigned to. Each Expense Policy contains a list of valid Expense Types. The Payment Types are associated with the user’s Expense Group and apply to all the returned policies. Only the payment types that are valid for the Post Expense Entry endpoint are returned.
NOTE: The Concur Expense product is highly configurable, and each client may have a unique set of payment types. If a payment type is not included in the response, it is not available for use with this client.
- Retrieve a configuration of an expense group
- Retrieve an expense group configuration by ID
- Schema
- Make a test call using 3.0 Swagger
Version
3.0
1.1 documentation is available here
Retrieve a configuration of an expense group
GET /api/v3.0/expense/expensegroupconfigurations
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
user |
string |
query |
The login ID of the user associated with this expense group configuration. The user must have the Web Services Admin role to use this parameter. |
offset |
string |
query |
The starting point of the next set of results, after the limit specified in the limit field has been reached. |
limit |
Int32 |
query |
The number of records to return Default value: 10 |
Request URL
https://www.concursolutions.com/api/v3.0/expense/expensegroupconfigurations?user=ALL&limit=10
JSON example of a successful response
{
"Items": [
{
"Name": "United Kingdom",
"AttendeeListFormID": "gWh2aF2cfwJElRBMIJ9ahYnTVXDIp1fQUdg",
"AttendeeListFormName": "Default Attendee Detail View",
"AllowUserRegisterYodlee": false,
"AllowUserDigitalTaxInvoice": false,
"CashAdvance": null,
"PaymentTypes": [
{
"ID": "gWurF7TC$pQAT4cqT0JokiYMobzQdz",
"Name": "Cash",
"IsDefault": false
},
{
"ID": "gWurL7jy84a4BAdqGaTNrtiABiqpM",
"Name": "Company Paid",
"IsDefault": false
},
{
"ID": "gWvnH$pTyEPYFerdCk8rjvoSpmM4L0",
"Name": "Pending Card Transaction",
"IsDefault": false
}
],
"Policies": [
{
"ID": "gWmINGEAkRfLbo7HmBh5USB3$pS8HMWDoP2Q",
"Name": "*Global Expense Policy",
"IsDefault": false,
"IsInheritable": true,
"ExpenseTypes": [
{
"Code": "LODNG",
"Name": "Hotel",
"ExpenseCode": "LODGING"
}
]
}
]
}
]
}
Retrieve an expense group configuration by ID
GET /api/v3.0/expense/expensegroupconfigurations/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the expense group configuration. |
user |
string |
query |
The login ID of the user associated with this expense group configuration. The user must have the Web Services Admin role to use this parameter. |
Expense Group Configurations - Schema
Expense Group Configurations
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the expense group configuration. |
user |
string |
query |
The login ID of the user associated with this expense group configuration. The user must have the Web Services Admin role to use this parameter. |
Expense Group Configuration
| Name | Type | Format | Description |
|---|---|---|---|
AllowUserDigitalTaxInvoice |
Boolean |
- | Indicates whether users are allowed to upload digital tax invoices. Format: true or false |
AllowUserRegisterYodlee |
Boolean |
- | Indicates whether users in the expense group are allowed to register Yodlee credit cards. Format: true or false |
AttendeeListFormID |
string |
- | The unique identifier for the attendee list form. |
AttendeeListFormName |
string |
- | The name of the attendee list form. |
AttendeeTypes |
array[AttendeeType] |
- | The list of attendee types. |
CashAdvance |
CashAdvance |
- | The amount of the cash advance. |
ID |
string |
- | The unique identifier of the resource. |
Name |
string |
- | The name of the expense group configuration. |
PaymentTypes |
array |
Payment Type | The list of payment types. |
Policies |
array |
Policy | The list of policies and expense types. |
URI |
string |
- | The URI to the resource. |
Attendee Type
| Name | Type | Format | Description |
|---|---|---|---|
Code |
string |
- | The attendee type code. |
Name |
string |
- | The name of the attendee type. |
Cash Advance
| Name | Type | Format | Description |
|---|---|---|---|
AllowUserCarryBalance |
Boolean |
- | Indicates whether users are allowed to carry a cash advance balance forward from one report to another. Format: true or false |
AllowUserLinkMultiple |
Boolean |
- | Indicates whether users are allowed to link multiple cash advances to one expense report. Format: true or false |
AllowUserUpdateExchangeRate |
Boolean |
- | Indicates whether users are allowed to update the currency exchange rate for expense entries. Format: true or false |
Name |
string |
- | The name of the cash advance workflow. |
WorkflowID |
string |
- | The unique identifier for the cash advance workflow. Null means there is no such workflow. |
Payment Type
| Name | Type | Format | Description |
|---|---|---|---|
ID |
string |
- | The unique identifier of the resource. |
IsDefault |
Boolean |
- | Determines whether this payment type is the default. Format: true or false |
Name |
string |
- | The name of the payment type. |
Policy
| Name | Type | Format | Description |
|---|---|---|---|
ExpenseTypes |
array |
ExpenseType | The parent element for the list of expense types in the policy. |
ID |
string |
- | The unique identifier of the resource. |
IsDefault |
Boolean |
- | Indicates whether this policy is the default. Format: true or false |
IsInheritable |
Boolean |
- | Indicates whether the descendent nodes in the Expense Feature Hierarchy are covered by this policy. Format: true or false |
Name |
string |
- | The name of the policy. |
Expense Group Configurations - Expense Type
| Name | Type | Format | Description |
|---|---|---|---|
Code |
string |
- | The code for the expense type. Expense types define expenses within an expense category. For example, Business Meal is an expense type in the MEALS category. |
ExpenseCode |
string |
- | The code for the expense category. The expense category code controls the function of an expense entry. Format: OTHER - Standard, COCARMILE - Company Car, PCARMILE - Personal Car, MFUEL - Fuel For Mileage, LODGING - Lodging, MEALS - Meals, OTHERNP - Other Not Partially Approvable, JPYPTRAN - Japanese Public Transportation |
Name |
string |
- | The name of the expense type. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/expensegroupconfigurations/gWv5bj%24sPY1weV9audTTRp7PkBlea3Y6aizg
JSON example of a successful response
{
"Name": "United Kingdom",
"AttendeeListFormID": "gWh2aF2cfwJElRBMIJ9ahYnTVXDIp1fQUdg",
"AttendeeListFormName": "Default Attendee Detail View",
"AllowUserRegisterYodlee": false,
"AllowUserDigitalTaxInvoice": false,
"CashAdvance": null,
"PaymentTypes": [
{
"ID": "gWurF7TC$pQAT4cqT0JokiYMobzQdz",
"Name": "Cash",
"IsDefault": false
},
{
"ID": "gWurL7jy84a4BAdqGaTNrtiABiqpM",
"Name": "Company Paid",
"IsDefault": false
},
{
"ID": "gWvnH$pTyEPYFerdCk8rjvoSpmM4L0",
"Name": "Pending Card Transaction",
"IsDefault": false
}
],
"Policies": [
{
"ID": "gWmINGEAkRfLbo7HmBh5USB3$pS8HMWDoP2Q",
"Name": "*Global Expense Policy",
"IsDefault": false,
"IsInheritable": true,
"ExpenseTypes": [
{
"Code": "LODNG",
"Name": "Hotel",
"ExpenseCode": "LODGING"
},
{
"Code": "LODTX",
"Name": "Hotel Tax",
"ExpenseCode": "LODGING"
},
{
"Code": "LNDRY",
"Name": "Laundry",
"ExpenseCode": "OTHER"
},
{
"Code": "AIRFR",
"Name": "Airfare",
"ExpenseCode": "OTHER"
},
{
"Code": "01026",
"Name": "Airline Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "CARRT",
"Name": "Car Rental",
"ExpenseCode": "OTHER"
},
{
"Code": "CARMI",
"Name": "Company Car Mileage",
"ExpenseCode": "COCARMILE"
},
{
"Code": "GASXX",
"Name": "Fuel",
"ExpenseCode": "OTHER"
},
{
"Code": "PARKG",
"Name": "Parking",
"ExpenseCode": "OTHER"
},
{
"Code": "MILEG",
"Name": "Personal Car Mileage",
"ExpenseCode": "PCARMILE"
},
{
"Code": "TRAIN",
"Name": "Public Transport",
"ExpenseCode": "OTHER"
},
{
"Code": "TAXIX",
"Name": "Taxi",
"ExpenseCode": "OTHER"
},
{
"Code": "TOLLS",
"Name": "Tolls/Road Charges",
"ExpenseCode": "OTHER"
},
{
"Code": "01025",
"Name": "Train",
"ExpenseCode": "OTHER"
},
{
"Code": "BRKFT",
"Name": "Breakfast",
"ExpenseCode": "OTHER"
},
{
"Code": "DINNR",
"Name": "Dinner",
"ExpenseCode": "OTHER"
},
{
"Code": "01028",
"Name": "Individual Meals",
"ExpenseCode": "OTHER"
},
{
"Code": "LUNCH",
"Name": "Lunch",
"ExpenseCode": "OTHER"
},
{
"Code": "BUSML",
"Name": "Entertainment - Clients",
"ExpenseCode": "OTHER"
},
{
"Code": "01004",
"Name": "Entertainment - Staff",
"ExpenseCode": "OTHER"
},
{
"Code": "01005",
"Name": "Courier/Shipping/Freight",
"ExpenseCode": "OTHER"
},
{
"Code": "OFCSP",
"Name": "Office Equipment/Hardware",
"ExpenseCode": "OTHER"
},
{
"Code": "01007",
"Name": "Office Supplies/Software",
"ExpenseCode": "OTHER"
},
{
"Code": "POSTG",
"Name": "Postage",
"ExpenseCode": "OTHER"
},
{
"Code": "01006",
"Name": "Printing/Photocopying/Stationery",
"ExpenseCode": "OTHER"
},
{
"Code": "01035",
"Name": "Business Calls",
"ExpenseCode": "OTHER"
},
{
"Code": "ONLIN",
"Name": "Internet/Online Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "CELPH",
"Name": "Mobile/Cellular Phone",
"ExpenseCode": "OTHER"
},
{
"Code": "01036",
"Name": "Non-Business Calls",
"ExpenseCode": "OTHER"
},
{
"Code": "LOCPH",
"Name": "Telephone/Fax",
"ExpenseCode": "OTHER"
},
{
"Code": "BANKF",
"Name": "Bank Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01024",
"Name": "Currency Exchange Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01011",
"Name": "Medical Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01008",
"Name": "Passports/Visa Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "AWRDS",
"Name": "Gifts - Clients",
"ExpenseCode": "OTHER"
},
{
"Code": "GIFTS",
"Name": "Gifts - Staff",
"ExpenseCode": "OTHER"
},
{
"Code": "TRDSH",
"Name": "Marketing/Promotional Costs",
"ExpenseCode": "OTHER"
},
{
"Code": "MISCL",
"Name": "Miscellaneous",
"ExpenseCode": "OTHER"
},
{
"Code": "01014",
"Name": "Newspapers/Magazines/Books",
"ExpenseCode": "OTHER"
},
{
"Code": "DUESX",
"Name": "Professional Subscriptions/Dues",
"ExpenseCode": "OTHER"
},
{
"Code": "SEMNR",
"Name": "Seminar/Course fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01009",
"Name": "Tips/Gratuities",
"ExpenseCode": "OTHER"
},
{
"Code": "01012",
"Name": "Tuition/Training Reimbursement",
"ExpenseCode": "OTHER"
},
{
"Code": "01010",
"Name": "Ex Pat Expenses",
"ExpenseCode": "OTHER"
},
{
"Code": "01017",
"Name": "Relocation Expenses",
"ExpenseCode": "OTHER"
},
{
"Code": "CSHRN",
"Name": "Cash Advance Return",
"ExpenseCode": "OTHERNP"
},
{
"Code": "CURGL",
"Name": "Currency Gain/Loss",
"ExpenseCode": "OTHERNP"
},
{
"Code": "01052",
"Name": "Fixed Vehicle Reimbursement",
"ExpenseCode": "OTHER"
},
{
"Code": "01053",
"Name": "Motus Other Amount",
"ExpenseCode": "OTHER"
},
{
"Code": "01054",
"Name": "Variable Vehicle Reimbursement",
"ExpenseCode": "OTHER"
}
]
},
{
"ID": "gWmINGEAkRfGsCKjw8DAec1dbfF$pV$sxbfpw",
"Name": "Germany Expense Policy",
"IsDefault": null,
"IsInheritable": null,
"ExpenseTypes": [
{
"Code": "LODNG",
"Name": "Hotel",
"ExpenseCode": "LODGING"
},
{
"Code": "LODTX",
"Name": "Hotel Tax",
"ExpenseCode": "LODGING"
},
{
"Code": "LNDRY",
"Name": "Laundry",
"ExpenseCode": "OTHER"
},
{
"Code": "AIRFR",
"Name": "Airfare",
"ExpenseCode": "OTHER"
},
{
"Code": "01026",
"Name": "Airline Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01002",
"Name": "Car Maintenance/Repairs ",
"ExpenseCode": "OTHER"
},
{
"Code": "CARRT",
"Name": "Car Rental",
"ExpenseCode": "OTHER"
},
{
"Code": "GASXX",
"Name": "Fuel",
"ExpenseCode": "OTHER"
},
{
"Code": "PARKG",
"Name": "Parking",
"ExpenseCode": "OTHER"
},
{
"Code": "MILEG",
"Name": "Personal Car Mileage",
"ExpenseCode": "PCARMILE"
},
{
"Code": "TRAIN",
"Name": "Public Transport",
"ExpenseCode": "OTHER"
},
{
"Code": "TAXIX",
"Name": "Taxi",
"ExpenseCode": "OTHER"
},
{
"Code": "TOLLS",
"Name": "Tolls/Road Charges",
"ExpenseCode": "OTHER"
},
{
"Code": "01025",
"Name": "Train",
"ExpenseCode": "OTHER"
},
{
"Code": "BRKFT",
"Name": "Breakfast",
"ExpenseCode": "OTHER"
},
{
"Code": "DINNR",
"Name": "Dinner",
"ExpenseCode": "OTHER"
},
{
"Code": "LUNCH",
"Name": "Lunch",
"ExpenseCode": "OTHER"
},
{
"Code": "01055",
"Name": "EBR 1190",
"ExpenseCode": "OTHER"
},
{
"Code": "01030",
"Name": "Entertainment - External (Domestic)",
"ExpenseCode": "OTHER"
},
{
"Code": "01031",
"Name": "Entertainment - External (Foreign)",
"ExpenseCode": "OTHER"
},
{
"Code": "01004",
"Name": "Entertainment - Staff",
"ExpenseCode": "OTHER"
},
{
"Code": "01005",
"Name": "Courier/Shipping/Freight",
"ExpenseCode": "OTHER"
},
{
"Code": "OFCSP",
"Name": "Office Equipment/Hardware",
"ExpenseCode": "OTHER"
},
{
"Code": "01007",
"Name": "Office Supplies/Software",
"ExpenseCode": "OTHER"
},
{
"Code": "POSTG",
"Name": "Postage",
"ExpenseCode": "OTHER"
},
{
"Code": "01006",
"Name": "Printing/Photocopying/Stationery",
"ExpenseCode": "OTHER"
},
{
"Code": "01035",
"Name": "Business Calls",
"ExpenseCode": "OTHER"
},
{
"Code": "ONLIN",
"Name": "Internet/Online Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "CELPH",
"Name": "Mobile/Cellular Phone",
"ExpenseCode": "OTHER"
},
{
"Code": "01036",
"Name": "Non-Business Calls",
"ExpenseCode": "OTHER"
},
{
"Code": "LOCPH",
"Name": "Telephone/Fax",
"ExpenseCode": "OTHER"
},
{
"Code": "BANKF",
"Name": "Bank Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01024",
"Name": "Currency Exchange Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01011",
"Name": "Medical Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01008",
"Name": "Passports/Visa Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01033",
"Name": "Gifts <= 35€",
"ExpenseCode": "OTHER"
},
{
"Code": "01032",
"Name": "Gifts > 35€",
"ExpenseCode": "OTHER"
},
{
"Code": "TRDSH",
"Name": "Marketing/Promotional Costs",
"ExpenseCode": "OTHER"
},
{
"Code": "MISCL",
"Name": "Miscellaneous",
"ExpenseCode": "OTHER"
},
{
"Code": "01014",
"Name": "Newspapers/Magazines/Books",
"ExpenseCode": "OTHER"
},
{
"Code": "DUESX",
"Name": "Professional Subscriptions/Dues",
"ExpenseCode": "OTHER"
},
{
"Code": "SEMNR",
"Name": "Seminar/Course fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01009",
"Name": "Tips/Gratuities",
"ExpenseCode": "OTHER"
},
{
"Code": "01012",
"Name": "Tuition/Training Reimbursement",
"ExpenseCode": "OTHER"
},
{
"Code": "01010",
"Name": "Ex Pat Expenses",
"ExpenseCode": "OTHER"
},
{
"Code": "01017",
"Name": "Relocation Expenses",
"ExpenseCode": "OTHER"
},
{
"Code": "CSHRN",
"Name": "Cash Advance Return",
"ExpenseCode": "OTHERNP"
},
{
"Code": "CURGL",
"Name": "Currency Gain/Loss",
"ExpenseCode": "OTHERNP"
}
]
},
{
"ID": "gWmINGEAkQoarrf1JiyI8$sqI$s00T30OfIlA",
"Name": "Italy Expense Policy",
"IsDefault": null,
"IsInheritable": null,
"ExpenseTypes": [
{
"Code": "LODNG",
"Name": "Hotel",
"ExpenseCode": "LODGING"
},
{
"Code": "LODTX",
"Name": "Hotel Tax",
"ExpenseCode": "LODGING"
},
{
"Code": "LNDRY",
"Name": "Laundry",
"ExpenseCode": "OTHER"
},
{
"Code": "AIRFR",
"Name": "Airfare",
"ExpenseCode": "OTHER"
},
{
"Code": "01026",
"Name": "Airline Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01002",
"Name": "Car Maintenance/Repairs ",
"ExpenseCode": "OTHER"
},
{
"Code": "CARRT",
"Name": "Car Rental",
"ExpenseCode": "OTHER"
},
{
"Code": "GASXX",
"Name": "Fuel",
"ExpenseCode": "OTHER"
},
{
"Code": "PARKG",
"Name": "Parking",
"ExpenseCode": "OTHER"
},
{
"Code": "MILEG",
"Name": "Personal Car Mileage",
"ExpenseCode": "PCARMILE"
},
{
"Code": "TRAIN",
"Name": "Public Transport",
"ExpenseCode": "OTHER"
},
{
"Code": "TAXIX",
"Name": "Taxi",
"ExpenseCode": "OTHER"
},
{
"Code": "TOLLS",
"Name": "Tolls/Road Charges",
"ExpenseCode": "OTHER"
},
{
"Code": "01025",
"Name": "Train",
"ExpenseCode": "OTHER"
},
{
"Code": "01043",
"Name": "Alcoholic Beverages & Softs Drinks",
"ExpenseCode": "MEALS"
},
{
"Code": "BRKFT",
"Name": "Breakfast",
"ExpenseCode": "OTHER"
},
{
"Code": "DINNR",
"Name": "Dinner",
"ExpenseCode": "OTHER"
},
{
"Code": "01028",
"Name": "Individual Meals",
"ExpenseCode": "OTHER"
},
{
"Code": "01044",
"Name": "Individual Meals - Within Municipality",
"ExpenseCode": "MEALS"
},
{
"Code": "LUNCH",
"Name": "Lunch",
"ExpenseCode": "OTHER"
},
{
"Code": "BUSML",
"Name": "Entertainment - Clients",
"ExpenseCode": "OTHER"
},
{
"Code": "01004",
"Name": "Entertainment - Staff",
"ExpenseCode": "OTHER"
},
{
"Code": "01005",
"Name": "Courier/Shipping/Freight",
"ExpenseCode": "OTHER"
},
{
"Code": "OFCSP",
"Name": "Office Equipment/Hardware",
"ExpenseCode": "OTHER"
},
{
"Code": "POSTG",
"Name": "Postage",
"ExpenseCode": "OTHER"
},
{
"Code": "01006",
"Name": "Printing/Photocopying/Stationery",
"ExpenseCode": "OTHER"
},
{
"Code": "01035",
"Name": "Business Calls",
"ExpenseCode": "OTHER"
},
{
"Code": "ONLIN",
"Name": "Internet/Online Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "CELPH",
"Name": "Mobile/Cellular Phone",
"ExpenseCode": "OTHER"
},
{
"Code": "01036",
"Name": "Non-Business Calls",
"ExpenseCode": "OTHER"
},
{
"Code": "LOCPH",
"Name": "Telephone/Fax",
"ExpenseCode": "OTHER"
},
{
"Code": "BANKF",
"Name": "Bank Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01024",
"Name": "Currency Exchange Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01008",
"Name": "Passports/Visa Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "AWRDS",
"Name": "Gifts - Clients",
"ExpenseCode": "OTHER"
},
{
"Code": "GIFTS",
"Name": "Gifts - Staff",
"ExpenseCode": "OTHER"
},
{
"Code": "TRDSH",
"Name": "Marketing/Promotional Costs",
"ExpenseCode": "OTHER"
},
{
"Code": "01014",
"Name": "Newspapers/Magazines/Books",
"ExpenseCode": "OTHER"
},
{
"Code": "DUESX",
"Name": "Professional Subscriptions/Dues",
"ExpenseCode": "OTHER"
},
{
"Code": "SEMNR",
"Name": "Seminar/Course fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01009",
"Name": "Tips/Gratuities",
"ExpenseCode": "OTHER"
},
{
"Code": "01012",
"Name": "Tuition/Training Reimbursement",
"ExpenseCode": "OTHER"
},
{
"Code": "01045",
"Name": "Undocumented Incidentals - Domestic",
"ExpenseCode": "OTHER"
},
{
"Code": "01046",
"Name": "Undocumented Incidentals - International",
"ExpenseCode": "OTHER"
},
{
"Code": "CSHRN",
"Name": "Cash Advance Return",
"ExpenseCode": "OTHERNP"
},
{
"Code": "CURGL",
"Name": "Currency Gain/Loss",
"ExpenseCode": "OTHERNP"
}
]
},
{
"ID": "gWmINGEAkQoapyOLKfSdm0A9qK0ZVUvwolA",
"Name": "US Expense Policy",
"IsDefault": null,
"IsInheritable": null,
"ExpenseTypes": [
{
"Code": "LODNG",
"Name": "Hotel",
"ExpenseCode": "LODGING"
},
{
"Code": "LODTX",
"Name": "Hotel Tax",
"ExpenseCode": "LODGING"
},
{
"Code": "INCTS",
"Name": "Incidentals",
"ExpenseCode": "OTHER"
},
{
"Code": "LNDRY",
"Name": "Laundry",
"ExpenseCode": "OTHER"
},
{
"Code": "01057",
"Name": "Test4",
"ExpenseCode": "OTHER"
},
{
"Code": "AIRFR",
"Name": "Airfare",
"ExpenseCode": "OTHER"
},
{
"Code": "01026",
"Name": "Airline Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01002",
"Name": "Car Maintenance/Repairs ",
"ExpenseCode": "OTHER"
},
{
"Code": "CARRT",
"Name": "Car Rental",
"ExpenseCode": "OTHER"
},
{
"Code": "CARMI",
"Name": "Company Car Mileage",
"ExpenseCode": "COCARMILE"
},
{
"Code": "GASXX",
"Name": "Fuel",
"ExpenseCode": "OTHER"
},
{
"Code": "PARKG",
"Name": "Parking",
"ExpenseCode": "OTHER"
},
{
"Code": "MILEG",
"Name": "Personal Car Mileage",
"ExpenseCode": "PCARMILE"
},
{
"Code": "TRAIN",
"Name": "Public Transport",
"ExpenseCode": "OTHER"
},
{
"Code": "TAXIX",
"Name": "Taxi",
"ExpenseCode": "OTHER"
},
{
"Code": "TOLLS",
"Name": "Tolls/Road Charges",
"ExpenseCode": "OTHER"
},
{
"Code": "01025",
"Name": "Train",
"ExpenseCode": "OTHER"
},
{
"Code": "BRKFT",
"Name": "Breakfast",
"ExpenseCode": "OTHER"
},
{
"Code": "01027",
"Name": "Business Meals (Attendees)",
"ExpenseCode": "OTHER"
},
{
"Code": "DINNR",
"Name": "Dinner",
"ExpenseCode": "OTHER"
},
{
"Code": "LUNCH",
"Name": "Lunch",
"ExpenseCode": "OTHER"
},
{
"Code": "BUSML",
"Name": "Entertainment - Clients",
"ExpenseCode": "OTHER"
},
{
"Code": "01004",
"Name": "Entertainment - Staff",
"ExpenseCode": "OTHER"
},
{
"Code": "01005",
"Name": "Courier/Shipping/Freight",
"ExpenseCode": "OTHER"
},
{
"Code": "OFCSP",
"Name": "Office Equipment/Hardware",
"ExpenseCode": "OTHER"
},
{
"Code": "01007",
"Name": "Office Supplies/Software",
"ExpenseCode": "OTHER"
},
{
"Code": "POSTG",
"Name": "Postage",
"ExpenseCode": "OTHER"
},
{
"Code": "01006",
"Name": "Printing/Photocopying/Stationery",
"ExpenseCode": "OTHER"
},
{
"Code": "01035",
"Name": "Business Calls",
"ExpenseCode": "OTHER"
},
{
"Code": "ONLIN",
"Name": "Internet/Online Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "CELPH",
"Name": "Mobile/Cellular Phone",
"ExpenseCode": "OTHER"
},
{
"Code": "01036",
"Name": "Non-Business Calls",
"ExpenseCode": "OTHER"
},
{
"Code": "LOCPH",
"Name": "Telephone/Fax",
"ExpenseCode": "OTHER"
},
{
"Code": "01047",
"Name": "Agency Booking Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "BANKF",
"Name": "Bank Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01024",
"Name": "Currency Exchange Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01008",
"Name": "Passports/Visa Fees",
"ExpenseCode": "OTHER"
},
{
"Code": "AWRDS",
"Name": "Gifts - Clients",
"ExpenseCode": "OTHER"
},
{
"Code": "GIFTS",
"Name": "Gifts - Staff",
"ExpenseCode": "OTHER"
},
{
"Code": "TRDSH",
"Name": "Marketing/Promotional Costs",
"ExpenseCode": "OTHER"
},
{
"Code": "MISCL",
"Name": "Miscellaneous",
"ExpenseCode": "OTHER"
},
{
"Code": "01014",
"Name": "Newspapers/Magazines/Books",
"ExpenseCode": "OTHER"
},
{
"Code": "DUESX",
"Name": "Professional Subscriptions/Dues",
"ExpenseCode": "OTHER"
},
{
"Code": "SEMNR",
"Name": "Seminar/Course fees",
"ExpenseCode": "OTHER"
},
{
"Code": "01038",
"Name": "Staff Awards/Incentives",
"ExpenseCode": "OTHER"
},
{
"Code": "01009",
"Name": "Tips/Gratuities",
"ExpenseCode": "OTHER"
},
{
"Code": "01012",
"Name": "Tuition/Training Reimbursement",
"ExpenseCode": "OTHER"
},
{
"Code": "CSHRN",
"Name": "Cash Advance Return",
"ExpenseCode": "OTHERNP"
},
{
"Code": "CURGL",
"Name": "Currency Gain/Loss",
"ExpenseCode": "OTHERNP"
},
{
"Code": "01052",
"Name": "Fixed Vehicle Reimbursement",
"ExpenseCode": "OTHER"
},
{
"Code": "01053",
"Name": "Motus Other Amount",
"ExpenseCode": "OTHER"
},
{
"Code": "01054",
"Name": "Variable Vehicle Reimbursement",
"ExpenseCode": "OTHER"
}
]
}
],
"AttendeeTypes": [
{
"Code": "PRIVATE",
"Name": "Attendee-Private List"
},
{
"Code": "HCOCGDM",
"Name": "Cegedim HCO Search–OneKey US"
}
],
"ID": "gWv5bj$sPY1weV9audTTRp7PkBlea3Y6aizg",
"URI": "https://www.concursolutions.com/api/v3.0/expense/expensegroupconfigurations/gWv5bj$sPY1weV9audTTRp7PkBlea3Y6aizg"
}
Itemizations
- Retrieve all expense itemizations owned by the user DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016
- Retrieve an expense itemization by ID
- Create a new expense itemization
- Update an expense itemization DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016
- Delete an expense itemization DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016
- Schema
Version
3.0 Note that some methods are deprecated
1.1 documentation is available here
Retrieve all expense itemizations owned by the user
DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016
GET /api/v3.0/expense/itemizations
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
reportID |
string |
query |
The report ID of the itemizations to be retrieved. Use the GET /expense/reportdigests function to find the report ID. Format: An alpha-numeric string |
entryID |
string |
query |
The entry ID for the itemizations to be retrieved. Use the GET /expense/entries endpoint to learn the valid entry ID. |
expenseTypeCode |
string |
query |
The expense type code for the itemizations to be retrieved. |
offset |
string |
query |
The starting point of the next set of results, after the limit specified in the limit field has been reached. |
limit |
Int32 |
query |
The number of records to return. Default value: 25 |
user |
string |
query |
The login ID of the user who owns the itemizations. The user must have the Web Services Admin role to use this parameter. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/itemizations?limit=10&user=ALL
JSON example of a successful response
{
"Items": [
{
"EntryID": "gWidFO7ikXSy55WZOaAXv8JRfFkruCwrP4g",
"ReportID": "F4F027007E814C1CA70E",
"ReportOwnerID": "CAtraveler@concurconnect2.com",
"ExpenseTypeCode": "LODTX",
"ExpenseTypeName": "Hotel Tax",
"SpendCategoryCode": "LODGA",
"SpendCategoryName": "Lodging - Track Room Rate Spending",
"TransactionDate": "2013-08-07T00:00:00",
"TransactionAmount": 20,
"PostedAmount": 20,
"ApprovedAmount": 20,
"LocationID": "gWqWg2EhaUtcIW$s2pMbTGM8W81u2qcfX94w",
"LocationName": "Montreal, Quebec",
"LocationSubdivision": "Quebec",
"LocationCountry": "CA",
"Description": "test",
"IsPersonal": false,
"IsBillable": false,
"IsImageRequired": false,
"AllocationType": "N",
"HasComments": false,
"HasExceptions": false,
"LastModified": "2013-09-02T19:40:48.877",
"OrgUnit1": null,
"OrgUnit2": null,
"OrgUnit3": null,
"OrgUnit4": null,
"OrgUnit5": null,
"OrgUnit6": null,
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"Custom6": null,
"Custom7": null,
"Custom8": null,
"Custom9": null,
"Custom10": null,
"Custom11": null,
"Custom12": null,
"Custom13": null,
"Custom14": null,
"Custom15": null,
"Custom16": null,
"Custom17": null,
"Custom18": null,
"Custom19": null,
"Custom20": null,
"Custom21": null,
"Custom22": null,
"Custom23": null,
"Custom24": null,
"Custom25": null,
"Custom26": null,
"Custom27": null,
"Custom28": null,
"Custom29": null,
"Custom30": null,
"Custom31": null,
"Custom32": null,
"Custom33": null,
"Custom34": null,
"Custom35": null,
"Custom36": null,
"Custom37": null,
"Custom38": null,
"Custom39": null,
"Custom40": null,
"ID": "gWidFO7ikXSy$seMkLiQismjUIYkxYzCsf4g",
"URI": "https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXSy$seMkLiQismjUIYkxYzCsf4g"
}
]
}
Retrieve an expense itemization by ID
GET /api/v3.0/expense/itemizations/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the expense itemization. |
user |
string |
query |
The login ID of the user who owns the itemizations. The user must have the Web Services Admin role to use this parameter. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXV6%24pcZsso2aBN0Aad4P5i8bjCg
JSON example of a successful response
{
"EntryID": "gWidFO7ikXV6$sQxTtWGQsIhawC4KoyssTCg",
"ReportID": "39BD9F7C5C3F4986A6A5",
"ReportOwnerID": "jimadmin@concurconnect2.com",
"ExpenseTypeCode": "LODTX",
"ExpenseTypeName": "Hotel Tax",
"SpendCategoryCode": "LODGA",
"SpendCategoryName": "Lodging - Track Room Rate Spending",
"TransactionDate": "2016-04-21T00:00:00",
"TransactionAmount": 20,
"PostedAmount": 20,
"ApprovedAmount": 20,
"LocationID": "gWqWg2EhcUKB$sottpx8eODvjn1$pWvWfG15A",
"LocationName": "Bellevue, Washington",
"LocationSubdivision": "Washington",
"LocationCountry": "US",
"Description": null,
"IsPersonal": false,
"IsBillable": false,
"IsImageRequired": false,
"AllocationType": "N",
"HasComments": false,
"HasExceptions": false,
"LastModified": "2016-04-22T22:19:55.213",
"OrgUnit1": null,
"OrgUnit2": null,
"OrgUnit3": null,
"OrgUnit4": null,
"OrgUnit5": null,
"OrgUnit6": null,
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"Custom6": null,
"Custom7": null,
"Custom8": null,
"Custom9": null,
"Custom10": null,
"Custom11": null,
"Custom12": null,
"Custom13": null,
"Custom14": null,
"Custom15": null,
"Custom16": null,
"Custom17": null,
"Custom18": null,
"Custom19": null,
"Custom20": null,
"Custom21": null,
"Custom22": null,
"Custom23": null,
"Custom24": null,
"Custom25": null,
"Custom26": null,
"Custom27": null,
"Custom28": null,
"Custom29": null,
"Custom30": null,
"Custom31": null,
"Custom32": null,
"Custom33": null,
"Custom34": null,
"Custom35": null,
"Custom36": null,
"Custom37": null,
"Custom38": null,
"Custom39": null,
"Custom40": null,
"ID": "gWidFO7ikXV6$pcZsso2aBN0Aad4P5i8bjCg",
"URI": "https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXV6$pcZsso2aBN0Aad4P5i8bjCg"
}
Create a new expense itemization
POST /api/v3.0/expense/itemizations
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
content |
- | body |
Required The expense itemization object to create. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/itemizations
JSON example of a successful response
{
"ID": "gWidFO7ikXV69FISvVWPbHe1Oj4FbCd0DCg",
"URI": "https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXV69FISvVWPbHe1Oj4FbCd0DCg"
}
Update an expense itemization
DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016
PUT /api/v3.0/expense/itemizations/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the expense itemization |
content |
- | body |
Required The partial or complete expense itemization object to update. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXV6%24pcZsso2aBN0Aad4P5i8bjCg
JSON example of a successful response
no content
Delete an expense itemization
DEPRECATED: 05/19/2016 UNSUPPORTED: 11/19/2016
DELETE /api/v3.0/expense/itemizations/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The ID of the expense itemization to delete. |
user |
string |
query |
Required The login ID of the user who owns the itemizations. The user must have the Web Services Admin role to use this parameter. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/itemizations/gWidFO7ikXV6%24pcZsso2aBN0Aad4P5i8bjCg
JSON example of a successful response
no content
Itemizations - Schema
Itemizations
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Itemization | The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
Itemization
| Name | Type | Format | Description |
|---|---|---|---|
AllocationType |
string |
- | The type of allocation for the itemization. Possible values: P - partial allocation, F - full allocation, N - no allocation. Use the GET /expense/allocations function to get information about this entry's allocations. |
ApprovedAmount |
Decimal |
- | The approved amount of the expense itemization, in the report currency. |
Custom1 through Custom40 |
CustomField |
- | The details from the Custom fields. These fields may not have data, depending on the configuration. If the form field is configured as a List data type, the value will be the item code for this list. Use the GET /common/listitems operation to learn the item name. Maximum length: 64 characters |
Description |
string |
- | The description of the expense. Maximum length: 64 characters |
EntryID |
string |
- | Required The ID of the expense entry that is the parent for the itemization. Use the GET /expense/entries endpoint to learn the entry ID for the expense itemizations. |
ExpenseTypeCode |
string |
- | Required The code for the expense type. Use the GET /expense/expensegroupconfigurations endpoint to learn the expense type code for expense types that are active for this report's policy. |
ExpenseTypeName |
string |
- | Required The name of the expense type, localized to the user's language. |
HasComments |
Boolean |
- | Indicates whether the expense has comments. Use the GET ExpenseEntryComments endpoint to get information about this entry's comments. Format: true or false |
HasExceptions |
Boolean |
- | Indicates whether the expense has exceptions. Format: true or false |
ID |
string |
- | The unique identifier of the resource. |
IsBillable |
Boolean |
- | Indicates whether the itemization is billable. Format: true or false |
IsImageRequired |
Boolean |
- | Indicates whether a receipt image is required for the entry. Format: true or false |
IsPersonal |
Boolean |
- | Indicates whether the itemization is personal (that is, non-reimbursable). Format: true or false |
LastModified |
DateTime |
- | The UTC date when the itemization was last modified. |
LocationCountry |
string |
- | The country where the expense was incurred. Format: 2-letter ISO 3166-1 country code |
LocationID |
string |
- | The unique identifier for the location where the expense was incurred. Use the GET /common/locations function to get information for this location. |
LocationName |
string |
- | The location where the expense was incurred, usually the city name. |
LocationSubdivision |
string |
- | The state, province, or other country subdivision where the expense was incurred. Format: ISO 3166-2:2007 country subdivision |
OrgUnit1 through OrgUnit6 |
CustomField |
- | The details from the Org Unit fields. These fields may not have data, depending on the configuration. If the form field is configured as a List data type, the value will be the item code for this list. Use the GET /common/listitems operation to learn the item name. Maximum length: 64 characters |
PostedAmount |
Decimal |
- | The amount of the expense itemization, in the report currency. |
ReportID |
string |
- | Required The ID of the report that is the parent for the itemization. Use the GET /expense/reportdigests endpoint to learn the report ID for the itemizations. |
ReportOwnerID |
string |
- | Required The login ID for the report owner. Use the GET User Information endpoint to learn details about this user. |
SpendCategoryCode |
string |
- | Required The code for the spending category that is specified for this itemization. |
SpendCategoryName |
string |
- | Required The name of the spending category that is specified for this itemization, localized to the user's language. |
TransactionAmount |
Decimal |
- | The amount of the expense itemization, in the transaction currency of the parent expense entry. |
TransactionDate |
DateTime |
- | Required The date when the good or service associated with this itemization was provided. Format: YYYY-MM-DD |
URI |
string |
- | The URI to the resource. |
Custom Field
| Name | Type | Format | Description |
|---|---|---|---|
Code |
string |
- | For list fields, this is the list item code. |
ListItemID |
string |
- | For list fields, this is the list item ID. |
Type |
string |
- | The custom field type. Possible values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text |
Value |
string |
- | The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters |
Integration Status
The integration status of the supplied object. Currently supports expense reports.
This resource allows developers to ensure that the necessary transactions to account for expenses and arrange payment for the expenses in a specified report were created in the financial system prior to committing the expense report in Concur Expense. If they were, the developer uses this function to indicate the report was successfully integrated and move the report forward in the workflow to the Paid step. In Concur Expense, when a report arrives at the Paid workflow step the report is committed, meaning its data can't be changed and it can't be sent back in the workflow.
URI
https://www.concursolutions.com/api/expense/expensereport/v2.0/integrationstatus/
Operations
Integration Status - Request
Request Parameters
Path Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
| report/{ReportID} | required | The report keyword and the ReportID for the report that has been successfully integrated into the financial system. The ReportID is returned in the ReportID element by the Get List of Reports and the Get Report Details responses. |
Headers
Authorization Header
Authorization header with OAuth token for valid SAP Concur user. Required. The OAuth consumer must have the following user role: Web Services Administrator
Content-Type Header
- application/json
- application/xml
Integration Status - Response
Content Types
- application/xml
- application/json
Integration Status - Schema
The response will include an ActionStatus parent element (XML), or an object (JSON) with the following child elements (XML) or name/value pairs (JSON).
ActionStatus elements
| Element | Description |
|---|---|
| Status | Whether the request was successful. Possible values: SUCCESS, FAILURE. |
| Message | Provides further details for errors. |
Integration Status - Examples
XML Example Request
POST https://www.concursolutions.com/api/expense/expensereport/v2.0/integrationstatus/report/nx2WRNzp18$wjehk%wqEL6EDHRwi9r$paQS1UqyL6a454QitqQ HTTP/1.1
Authorization: OAuth {access token}
Accept: application/xml
...
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
<ActionStatus xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Message>SUCCESS</Message>
<Status>SUCCESS</Status>
</ActionStatus>
JSON Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"Status": "SUCCESS",
"Message": "SUCCESS"
}
JSON Example of Response with Error
HTTP/1.1 200 OK
Content-Type: application/json
{
"Status": "FAILURE",
"Message": "To use the POST Expense Journal Entry Job Key the report must be at the Processing Payment or Payment Confirmed Payment Status."
}
Create an exception to a report
Posts an exception to the report, and associates it with one of the following data levels: Report Header, Entry, Itemization, Allocation. This endpoint requires familiarity with the company's exception code configuration.
Create an exception to a report - Request
Request Parameters
Path Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
| {reportKey}/Exceptions | required | The identifier for the desired report and the exceptions keyword. |
Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/{reportKey}/Exceptions
URI Source: The reportKey value is returned in the RptKey element by the Get Report Details response.
Headers
Authorization Header
Authorization header with OAuth token for valid SAP Concur user. Required.
Content-Type Header
application/xml
Create an exception to a report - Request Schema
This request should contain an Exceptions parent element with an Exception parent element for each exception included in the report. The Exception element contains the following child elements:
Exception Elements
| Element | Required (must contain value)? | Description |
|---|---|---|
| Index | Y | The exception's location in a batch of exceptions. Should start at 1 and increment sequentially. This value is used to identify the record if there is an error. |
| ObjectType | Y | The type of object to assign the exception. Format: Report, Entry, or Allocation. When sending a Report level exception, the ObjectType and ObjectId can be null, as the report key is supplied in the URI. |
| ObjectId | Y | The unique identifier for the object to associate with the exception. Returned by the Get Report Details function. Must be the value from one of the following fields: Entry or Itemization: Use the RpeKey. Allocation: Use AllocationKey. Report Header: Null value. When sending a Report level exception, the ObjectType and ObjectId can be null, as the report key is supplied in the URI. |
| ExceptionCode | Y | The Exception Code for the exception to assign to the object. Must be a configured exception code in Expense. Example: NODATE |
Create an exception to a report - Response
Content Types
application/xml
Create an exception to a report - Response Schema
This request will return an exception-result parent element.
Exception-Result Elements
| Element | Description |
|---|---|
| exceptions-succeeded | The number of exceptions processed that were successfully assigned. |
| exceptions-failed | The number of exceptions processed that were not successfully added. |
| errors | This will contain an error parent element for each record failure. The error element will contain the following child elements: Index: The exception's location in the batch. message: The error message. |
| ExceptionDetails | This parent element will contain an ExceptionInfo parent element for all exceptions that did not cause an error, and will contain the following child elements: Index: The exception's location in the batch. Status: The status of the request. |
Create an exception to a report - Examples
XML Example Request
POST https://www.concursolutions.com/api/expense/expensereport/v1.1/report/3FK118eIJ844Uwl0HF32/Exceptions HTTP/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
<Exceptions xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Exception>
<Index>1</Index>
<ObjectType>Report</ObjectType>
<ObjectId>nxxKgLlnRODp$sie8Hq1UviOJ2AbpS7dCP</ObjectId>
<ExceptionCode>APPRVTO</ExceptionCode>
</Exception>
<Exception>
<Index>2</Index>
<ObjectType>Entry</ObjectType>
<ObjectId>nxxKgLlnRODp$sie8Hq1UviOJ2deAbpS7dC0</ObjectId>
<ExceptionCode>APPRVTO</ExceptionCode>
</Exception>
</Exceptions>
XML Example of Response With Success and Failure
<exception-result xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<exceptions-succeeded>1</exceptions-succeeded>
<exceptions-failed>1</exceptions-failed>
<errors>
<error>
<Index>2</Index>
<message>Invalid Exception Code</message>
</error>
</errors>
<ExceptionDetails>
<ExceptionInfo>
<Index>1</Index>
<Status>Success</Status>
</ExceptionInfo>
</ExceptionDetails>
</exception-result>
Submit an expense report
Triggers the Submit workflow action for the specified report.
Important Note: This endpoint submits the expense report as if the original report owner had submitted it. Consult your company's Expense administrator to confirm that the web service should be allowed to submit reports on behalf of users. If you wish to enforce the expense report delegate functionality, use the Get Expense Delegators function to determine if the user in question has the correct permissions to submit on behalf of the report owner.
Submit An Expense Report - Request
Request Parameters
Path Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
| {reportKEY}/submit | required | The identifier for the desired report and the submit keyword. |
Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/{reportKEY}/submit
URI Source: The reportId value is returned by the Get List of Reports and Get Report Details functions, and as part of the Report-Details-Url element of the Post Expense Report Header function.
Content Types
application/xml
Authorization Header
Authorization: This request requires an Authorization header with an OAuth token for a valid SAP Concur user.
X_UserID: This request requires an additional field in the authorization header, identifying the report owner. This identifier is the SAP Concur login for the user, and is often also the email address of the user. The field format is:
X_UserID: expenseuser@example.com
Submit An Expense Report - Response
Submit An Expense Report - Schema
This request will return a ReportStatus parent element with the following child elements.
Report Status Elements
| Element | Description |
|---|---|
| Message | The error message. Only appears if a submission error was generated. |
| Status | The status of the report submit action. |
If the report submission triggered an exception, a ReportExceptions parent element will be provided, with a ReportException parent element for each exception. The ReportException element contains the following elements.
Report Exception Schema
| Element | Description |
|---|---|
| CrnCode | The currency code of the entry. |
| EventCode | The event that resulted in the exception. |
| ExceptionCode | The company-defined exception code. |
| ExceptionErrorCode | The severity of the exception. Exceptions with ERROR as the code cannot be submitted. |
| ExceptionVisibility | Which users are able to see the exception. |
| ExpKey | The expense type key for the entry. |
| ExpName | The expense type name for the entry. |
| IsCleared | Whether the exception has been cleared by the Expense Processor. |
| SeverityLevel | A numeric value indicating the severity level of the exception. The value threshold is configurable. |
| TransactionAmount | The amount of the entry. |
| TransactionDate | The date of the entry. |
| Type | The exception type. |
Submit An Expense Report - Examples
XML Example Request
POST https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nxxKgLlnROz$sQ6SKJFjLNs4OWBErcJ8yX/submit HTTP/1.1
Authorization: OAuth {access token}
X-UserID: cmiller@example.com
...
XML example of Successful Response
<ReportStatus xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Status>SUCCESS</Status>
</ReportStatus>
Post an expense report workflow action
Posts a workflow action for the supplied expense report. The workflow action moves the expense report through the workflow process.
Workflow Actions
The available actions are:
- Approve: The report successfully completes the current workflow step. The report will continue in the workflow, and may require additional approvals based on configuration. If the report was in the Processing Payment status, it will be moved to the Paid status.
NOTES:- Reports can't be moved from Processing Payment to Paid until all of their expense entries have been extracted or manually paid. Wait until the extract process completes for the report, then send the Approve workflow action.
- This API is not supported for the Processor role or expense reports pending the Processor workflow step.
- Send Back to Employee: The report is sent back to the employee for revision. When the user resubmits the report, it travels through the entire workflow again.
- Recall to Employee: This workflow action is initiated by the employee, and is only available after the report has been submitted. This workflow action may not be available to some clients due to configuration.
WARNING: Prior to calling this endpoint the Caller must check the Approval Status found in the ApprovalStatusName element in the response for Get Report Details to ensure the report is at the workflow step the Caller expects. Under no circumstance should a Caller make a call to this endpoint without being certain the report is at the workflow step the Caller expects.
Workflow Roles
Each workflow step in a workflow is associated with a workflow role. Professional clients can configure workflow steps and roles in the Workflows area of Expense Admin. The OAuth consumer is evaluated to determine which role(s) the consumer has in SAP Concur. There are two different types of workflow roles as described in the following sections.
System Role
The System role is used when the workflow actions can be completed programatically. Any workflow action can be completed this way, depending on the client's business process. The workflow role can be configured while adding the report workflow step. Some steps may require the System role. When using this role, the OAuth consumer must have the following user role:
- Standard/Developer Sandbox: Can Administer
- Professional: Company Admin or Web Services Administrator
The expense report owner must have an approver or processor assigned to them before the System role can make changes to their reports.
Approver Role
The Approver role is used when the workflow action should be completed by a particular user. Developers who want to present a list of reports to approve and send the workflow action when the reports have been evaluated by the approver use the Approver role. This role requires that a user with the correct SAP Concur role (Expense Approver, Authorized Approver, Cost Object Approver, or Expense Processor for Professional, or the Can Administer or Can Approve Reports roles for Standard) authenticates using Standard OAuth before supplying the workflow action. The user must also have access (be a valid approver or processor) for the supplied report ID.
Post an expense report workflow action - Request
Request Parameters
Path Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
| {workflowstepID}/workflowaction | required | The identifier for the desired workflow step and the workflowaction keyword. |
Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/{workflowstepId}/workflowaction
URI Source: The URI is returned in the WorkflowActionURL element of the Get Report Details response.
Headers
Authorization Header
Authorization header with OAuth token for valid SAP Concur user. Required.
Content-Type Header
application/xml
Request Body
Post an expense report workflow action - Request Schema
This request should contain a WorkflowAction parent element with the following child elements.
WorkflowAction Child Elements
| Element | Required/optional | Description |
|---|---|---|
| Action | required | The name of the workflow action. Possible values are: Approve, Send Back to Employee, or Recall to Employee. Must be one of the workflow actions available for the workflow step. Consult Expense Admin > Workflow to learn details. |
| Comment | required, for Send Back to Employee | Must be used with the Send Back to Employee workflow action. This comment is visible wherever report comments are available to the employee, approver, authorization request administrator, and/or processor. Max length: 2000 |
Post an expense report workflow action - Response
Post an expense report workflow action - Response Schema
This request will return an ActionStatus parent element with the following child elements.
ActionStatus Elements
| Element | Description |
|---|---|
| Message | The error message. Only appears if a workflow action error was generated. |
| Status | The status of the report workflow action. |
Post an expense report workflow action - Examples
XML Example Request
POST https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nx2WRNzp18$wjehk%wqEL6EDHRwi9r$paQS1UqyL6a454QitqQ/workflowaction HTTP/1.1
Authorization: OAuth {access token}
...
<WorkflowAction xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03">
<Action>Approve</Action>
<Comment>Approved via SAP Concur</Comment>
</WorkflowAction>
XML Example of Successful Response
<?xml version="1.0" encoding="utf-8"?>
<ActionStatus xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Message>SUCCESS!</Message>
<Status>SUCCESS!</Status>
</ActionStatus>
XML Example of Response with Error
<?xml version="1.0" encoding="utf-8"?>
<ActionStatus xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Message>The action cannot be executed because the item has recently been changed. Please refresh your list and try again.</Message>
<Status>FAILURE</Status>
</ActionStatus>
Reports v3
- Retrieve reports owned by the user based on search criteria
- Retrieve a report by ID
- Create a new report
- Update a report
- Schema
Prior Versions
Retrieve reports owned by the user based on search criteria
GET /api/v3.0/expense/reports
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
offset |
string |
query |
Starting page offset |
limit |
Int32 |
query |
Number of records to return (default 25) |
user |
string |
query |
Optional. The login ID of the report owner(s) to use when searching for reports. If the value is set to LoginID, reports for the report owner with this login ID value are returned. If the value is set to ALL, reports for all report owners are returned. If this parameter is not specified, reports for the OAuth Consumer are returned. The access token owner (OAuth Consumer) must have the Web Services Admin role to use this parameter. |
approvalStatusCode |
string |
query |
The status code for the Approval Status. The values can include Concur Expense standard codes or custom codes. The Concur Expense standard code values are: A_AAFH - Report submission triggered an anomaly and fraud check; A_ACCO - Report is pending reviews; A_APPR - Report has been approved; A_EXTV - Report is pending external validation; A_FILE - Report has been submitted; A_NOTF - Report has not been submitted; A_PBDG - Report approval is pending Budget approval; A_PECO - Report approval is pending Cost object approval; A_PEND - Report is pending manager approval; A_PVAL - Report is pending prepayment validation; A_RESU - Report needs to be resubmitted; A_RHLD - Report submission is pending receipt images; A_TEXP - Report expired in approval queue. For custom codes, contact Concur Developer Support. |
paymentStatusCode |
string |
query |
The payment status code for the report. The values can include Concur Expense standard codes or custom codes. The Concur Expense standard code values are: P_HOLD - Report payment is on hold; P_NOTP - Report has not been paid; P_PAID - Report has been paid; P_PAYC - Payment is confirmed. Some or all of the report expenses have been paid; P_PROC - Report is in process to be paid. For custom codes, contact Concur Developer Support. |
currencyCode |
string |
query |
The 3-letter ISO 4217 currency code for the report currency. Example: USD. |
paymentType |
string |
query |
The unique identifier for the payment type that is the payment type for at least one expense entry in the report. Use PaymentTypeID from Response of GET Expense Group Configurations V3 to obtain valid payment types. |
reimbursementMethod |
string |
query |
The method the report owner will be reimbursed. VALUES: ADPPAYR - ADP Payroll; APCHECK - AP (Company Check); CNQRPAY - Expense Pay; PMTSERV - Other Payment Service. NOTE: PAY_PAL is NOT supported. |
approverLoginID |
string |
query |
The login ID for the report approver that is the current approver assigned to the report. |
expenseTypeCode |
string |
query |
The expense type code that is the expense type for at least one expense entry in the report. Use ExpenseTypeCode from Response of GET Expense Group Configurations V3. |
attendeeTypeCode |
string |
query |
The report contains expense entries that have attendees of the specified type. |
countryCode |
string |
query |
The report country. Maximum 2 characters. Format: The ISO 3166-1 alpha-2 country code. Example: United States is US. |
batchID |
string |
query |
The unique identifier for a payment batch where there is at least one report payee within the report. Use the BatchID from Response of GET Payment Batch List. |
vendorName |
string |
query |
The Vendor Description that is the vendor for at least one expense entry in the report. |
hasVAT |
Boolean |
query |
Determines if the report has at least one expense entry with VAT details. Format: true or false. |
hasImages |
Boolean |
query |
Determines if the report has at least one expense entry with an entry image or if there is a report image for this report. Format: true or false. |
hasAttendees |
Boolean |
query |
Determines if the report has at least one expense entry with an attendee. Format: true or false. |
hasBillableExpenses |
Boolean |
query |
The IsBillable flag for at least one expense entry in the report. Format: true or false. |
isTestUser |
Boolean |
query |
The report owner is a test user using the report for testing purposes in a non-production environment. Format: true or false. |
expenseGroupConfigID |
string |
query |
The unique identifier for the expense group configuration associated to the report's expense group. Use the ID from the Response of the Expense Group Configurations V3. |
entryTransactionDateBefore |
DateTime |
query |
The entry transaction date for at least one expense entry in the report is before this date. Format: YYYY-MM-DD |
entryTransactionDateAfter |
DateTime |
query |
The entry transaction date for at least one expense entry in the report is after this date. Format: YYYY-MM-DD |
createDateBefore |
DateTime |
query |
The report create date is before this date. Format: YYYY-MM-DD |
createDateAfter |
DateTime |
query |
The report create date is after this date. Format: YYYY-MM-DD |
userDefinedDateBefore |
DateTime |
query |
The report user defined date is before this date. Format: YYYY-MM-DD |
userDefinedDateAfter |
DateTime |
query |
The report user defined date is after this date. Format: YYYY-MM-DD |
submitDateBefore |
DateTime |
query |
The report submit date is before this date. Format: YYYY-MM-DD |
submitDateAfter |
DateTime |
query |
The report submit date is after this date. Format: YYYY-MM-DD |
processingPaymentDateBefore |
DateTime |
query |
The report processing payment date is before this date. Format: YYYY-MM-DD |
processingPaymentDateAfter |
DateTime |
query |
The report processing payment date is after this date. Format: YYYY-MM-DD |
paidDateBefore |
DateTime |
query |
The report paid date is before this date. Format: YYYY-MM-DD |
paidDateAfter |
DateTime |
query |
The report paid date is after this date. Format: YYYY-MM-DD |
modifiedDateBefore |
DateTime |
query |
The report modified date is before this date. Format: YYYY-MM-DD |
modifiedDateAfter |
DateTime |
query |
The report modified date is after this date. Format: YYYY-MM-DD |
Request URL
https://www.concursolutions.com/api/v3.0/expense/reports?limit=15&user=ALL
JSON example of a successful response
{
"Items": [
{
"Name": "Canadian Tax",
"Total": 1900,
"CurrencyCode": "CAD",
"Country": "CA",
"CountrySubdivision": "CA-BC",
"CreateDate": "2013-09-02T19:05:57.687",
"SubmitDate": "2013-09-02T19:18:35.537",
"ProcessingPaymentDate": "2013-09-02T19:40:48.533",
"PaidDate": "2013-09-02T19:46:01.57",
"ReceiptsReceived": false,
"UserDefinedDate": "2013-09-02T00:00:00",
"LastComment": "",
"OwnerLoginID": "CAtraveler@concurconnect2.com",
"OwnerName": "Canadian Traveler",
"ApproverLoginID": null,
"ApproverName": null,
"ApprovalStatusName": "Approved",
"ApprovalStatusCode": "A_APPR",
"PaymentStatusName": "Sent for Payment",
"PaymentStatusCode": "P_PAID",
"LastModifiedDate": "2013-09-02T19:46:01.98",
"PersonalAmount": 0,
"AmountDueEmployee": 1500,
"AmountDueCompanyCard": 0,
"TotalClaimedAmount": 1900,
"TotalApprovedAmount": 1900,
"LedgerName": "DEFAULT",
"PolicyID": "gWmINGEAkQoamAzOARD9NEBtuv0ppnbJ4lQ",
"EverSentBack": false,
"HasException": false,
"WorkflowActionUrl": "http://www.concursolutions.com/api/v3.0/expense/reports/report/gWpkOyRxJoH6lOiUHqNhW93UWxhOZZw/WorkFlowAction?limit=15&user=ALL",
"OrgUnit1": null,
"OrgUnit2": null,
"OrgUnit3": null,
"OrgUnit4": null,
"OrgUnit5": null,
"OrgUnit6": null,
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"Custom6": null,
"Custom7": null,
"Custom8": null,
"Custom9": null,
"Custom10": null,
"Custom11": null,
"Custom12": null,
"Custom13": null,
"Custom14": null,
"Custom15": null,
"Custom16": null,
"Custom17": null,
"Custom18": null,
"Custom19": null,
"Custom20": null,
"ID": "F4F027007E814C1CA70E",
"URI": "https://www.concursolutions.com/api/v3.0/expense/reports/F4F027007E814C1CA70E"
}
]
}
Retrieve a report by ID
GET /api/v3.0/expense/reports/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required Report ID |
user |
string |
query |
Optional. The login ID of the report owner(s) to use when searching for reports. If the value is set to LoginID, reports for the report owner with this login ID value are returned. If the value is set to ALL, reports for all report owners are returned. If this parameter is not specified, reports for the OAuth Consumer are returned. The access token owner (OAuth Consumer) must have the Web Services Admin role to use this parameter. |
Request URL
https://www.concursolutions.com/api/v3.0/expense/reports/39BD9F7C5C3F4986A6A5
JSON example of a successful response
{
"Name": "Test 02",
"Total": 307.01,
"CurrencyCode": "USD",
"Country": "US",
"CountrySubdivision": null,
"CreateDate": "2016-04-04T23:33:08.21",
"SubmitDate": null,
"ProcessingPaymentDate": null,
"PaidDate": null,
"ReceiptsReceived": false,
"UserDefinedDate": "2016-04-04T00:00:00",
"LastComment": "",
"OwnerLoginID": "jimadmin@concurconnect2.com",
"OwnerName": "Jim Admin",
"ApproverLoginID": null,
"ApproverName": null,
"ApprovalStatusName": "Not Submitted",
"ApprovalStatusCode": "A_NOTF",
"PaymentStatusName": "Not Paid",
"PaymentStatusCode": "P_NOTP",
"LastModifiedDate": "2016-04-23T02:53:23.7",
"PersonalAmount": 0,
"AmountDueEmployee": 290,
"AmountDueCompanyCard": 0,
"TotalClaimedAmount": 307.01,
"TotalApprovedAmount": 307.01,
"LedgerName": "DEFAULT",
"PolicyID": "gWmINGEAkQoapyOLKfSdm0A9qK0ZVUvwolA",
"EverSentBack": false,
"HasException": true,
"WorkflowActionUrl": "",
"OrgUnit1": null,
"OrgUnit2": null,
"OrgUnit3": null,
"OrgUnit4": null,
"OrgUnit5": null,
"OrgUnit6": null,
"Custom1": null,
"Custom2": null,
"Custom3": null,
"Custom4": null,
"Custom5": null,
"Custom6": null,
"Custom7": null,
"Custom8": null,
"Custom9": null,
"Custom10": null,
"Custom11": null,
"Custom12": null,
"Custom13": null,
"Custom14": null,
"Custom15": null,
"Custom16": null,
"Custom17": null,
"Custom18": null,
"Custom19": null,
"Custom20": null,
"ID": "39BD9F7C5C3F4986A6A5",
"URI": "http://www.concursolutions.com/api/v3.0/expense/reports/39BD9F7C5C3F4986A6A5"
}
Create a new report
Note: Expense reports will be created under the user's default expense policy. If a user has two expense policies - default and purchasing card - passing the PolicyKey on the post body will be ignored by Expense. That is, the expense report will always be under the default expense policy.
POST /api/v3.0/expense/reports
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
content |
- | body |
Required Report object to create |
Update a report
Request URL
https://www.concursolutions.com/api/v3.0/expense/reports
JSON example of a successful response
{
"ID": "DD683A53018A4349B7CD",
"URI": "https://www.concursolutions.com/api/v3.0/expense/reports/DD683A53018A4349B7CD"
}
PUT /api/v3.0/expense/reports/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The unique identifier for the report. |
content |
body |
Required The report object to update |
Reports v3 - Schema
Reports
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Report | The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
Report
| Name | Type | Format | Description |
|---|---|---|---|
AmountDueCompanyCard |
Decimal |
- | The total amount due to the company card for the report. Maximum 23 characters. |
AmountDueEmployee |
Decimal |
- | The total amount due to the employee for the report. Maximum 23 characters. |
ApprovalStatusCode |
string |
- | The approval status code for the report. |
ApprovalStatusName |
string |
- | The report's approval status, in the OAuth consumer's language. |
ApproverLoginID |
string |
- | The Login ID of the report owner's expense approver. |
ApproverName |
string |
- | The name of the report owner's expense approver. |
Country |
string |
- | The report country. Maximum 2 characters. Format: The ISO 3166-1 alpha-2 country code. Example: United States is US. |
CountrySubdivision |
string |
- | The report country subdivision. Format: ISO 3166-2:2007 country subdivision. |
CreateDate |
DateTime |
- | The date the report was created. |
CurrencyCode |
string |
- | The 3-letter ISO 4217 currency code for the expense report currency. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona. |
Custom1 thorugh Custom20 |
CustomField |
- | The details from the Custom fields. These may not have data, depending on configuration. |
EverSentBack |
Boolean |
- | Whether the report has ever been sent back to the employee. Format: Y/N |
HasException |
Boolean |
- | Whether the report has exceptions. Format: Y/N |
ID |
string |
- | The unique identifier of the resource. |
LastComment |
string |
- | The text of the most recent comment on the report. |
LastModifiedDate |
DateTime |
- | The date the report header was last modified. |
LedgerName |
string |
- | The name of the expense report ledger. Maximum 20 characters. |
Name |
string |
- | Required The name of the report. |
OrgUnit1 through OrgUnit6 |
CustomField |
- | The details from the Org Unit fields. These may not have data, depending on configuration. |
OwnerLoginID |
string |
- | The Login ID of the user this report belongs to. |
OwnerName |
string |
- | The name of the expense report owner. |
PaidDate |
DateTime |
- | The date when all journal entries in the report was integrated with or extracted to the financial system. |
PaymentStatusCode |
string |
- | The code for the payment status of the report. |
PaymentStatusName |
string |
- | The report's payment status, in the OAuth consumer's language. |
PersonalAmount |
Decimal |
- | The total amount of expenses marked as personal. Maximum 23 characters. |
PolicyID |
string |
- | The unique identifier of the policy that applies to this report. Maximum 64 characters. User's default expense policy is being used when creating a new expense report |
ProcessingPaymentDate |
DateTime |
- | The date that the report completed all approvals and was ready to be extracted for payment. |
ReceiptsReceived |
Boolean |
- | If Y, then this entry has been marked as confirmed by the Expense Processor. Format: Y/N |
SubmitDate |
DateTime |
- | The date the report was submitted. |
Total |
Decimal |
- | The total amount of the report. |
TotalApprovedAmount |
Decimal |
- | The total amount of approved expenses in the report. Maximum 23 characters. |
TotalClaimedAmount |
Decimal |
- | The total amount of all non-personal expenses in the report. Maximum 23 characters. |
URI |
string |
- | The URI to the resource. |
UserDefinedDate |
DateTime |
- | The date of the report assigned by the user. |
WorkflowActionUrl |
string |
- | The URL to post a workflow action to the report using the Post Report Workflow Action function. |
Custom Field
| Name | Type | Format | Description |
|---|---|---|---|
Code |
string |
- | For list fields, this is the list item code. |
ListItemID |
string |
- | For list fields, this is the list item ID. |
Type |
string |
- | The custom field type. Possible values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text |
Value |
string |
- | The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters |
Request URL
https://www.concursolutions.com/api/v3.0/expense/reports/39BD9F7C5C3F4986A6A5
JSON example of a successful response
no content
Report details
Retrieves the full set of information for the report. Includes the Report Header, Entry, Attendee, Itemization and Allocation details.
Some elements will appear only if the OAuth consumer has the Web Services Admin role. These include: The ReportKey element, the employee's credit card information, and the employee's bank account information, VAT information, Journal entries. Connectors that utilize this information go through a review process with SAP Concur that includes verification of secure data handling.
GET list of reports can be found [here]((#reports-v2)
Report Details - Request
Request Parameters
Path Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
| reportId | required | The identifier for the desired report. |
Example: https://www.concursolutions.com/api/expense/expensereport/v2.0/report/{reportId}
URI Source: The ReportId is returned in the ReportId element of the Get List of Reports function
Headers
Authorization Header
Authorization header with OAuth token for valid SAP Concur user. The OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. These roles allow the user to manage data for the entire company.
Accept Header
application/xml
Report Details - Response
Content Types
application/xml
Report Details - Schema
This request will return a ReportDetails parent element.
ReportDetails
| Element | Description |
|---|---|
| UserLoginID | The user ID of the report owner. Maximum 128 characters. |
| EmployeeName | The name of the employee who created the report. Maximum 66 characters. |
| ReportID | The unique identifier for the report, which appears in the Concur Expense UI. Maximum 32 character varchar. |
| ReportKey | The unencrypted unique identifier for the report, that appears on the report header. The element appears only if the OAuth consumer has the Web Services Admin role in SAP Concur. Maximum 48 characters. |
| ReportName | The name of the report. Maximum 40 characters. |
| Purpose | The information from the Business Purpose field. |
| ReportDate | The date from the report header. Format: YYYY-MM-DDThh:mm:ss |
| CreationDate | The date the report was created. Format: YYYY-MM-DDThh:mm:ss |
| SubmitDate | The date the report was submitted. Maximum 10 characters. |
| PaidDate | The date the report was extracted for payment. This element has an attribute named i:nil. If the value for this element is null, the i:nil attribute will be set to true. Format: YYYY-MM-DDThh:mm:ss |
| CurrencyCode | The 3-letter ISO 4217 currency code for the expense report currency. The expense report currency is defined as the report creator's default reimbursement currency. |
| ReportTotal | The total amount of the report. Maximum 23 characters. |
| PersonalExpenses | The total amount of expenses marked as personal. Maximum 23 characters. |
| AmountDueEmployee | The total amount due to the employee for the report. Maximum 23 characters. |
| AmountDueCompanyCard | The total amount due to the company card for the report. Maximum 23 characters. |
| TotalClaimedAmount | The total amount of all non-personal expenses in the report. Maximum 23 characters. |
| TotalApprovedAmount | The total amount of approved expenses in the report. Maximum 23 characters. |
| ApprovalStatusCode | The approval status code for the report. |
| ApprovalStatusName | The approval status name for the report. |
| PaymentStatusCode | The unique identifier for the payment status of the report. |
| PaymentStatusName | The payment status of the report. |
| OrgUnit1 through OrgUnit6 | The details from the Org Unit custom fields. These may not have data, depending on configuration. Maximum 48 characters for each field. |
| Custom1 through Custom20 | The details from the Custom fields. These may not have data, depending on configuration. If report owner information is stored in these fields, it may be outdated. Refer to the ReportOwner parent element for the current owner information. Refer to the Custom Fields Child Elements table for more information. |
| LedgerName | The name of the expense report ledger. Maximum 20 characters. |
| PolicyID | The unique identifier of the policy that applies to this report. Maximum 64 characters. |
| EverSentBack | Whether the report has ever been sent back to the employee. Format: Y/N |
| HasException | Whether the report has exceptions. Format: Y/N |
| WorkflowActionURL | The URL to post a workflow action to the report using the Post Report Workflow Action function. |
| ExpenseEntriesList | This parent element has an ExpenseEntry child element for each entry. Refer to the ExpenseEntry elements table for more information. |
| ReportImageURL | The URL to access the image associated with the report. This URL is valid for 30 minutes after the web service call. |
| Country | The report country. Maximum 2 characters. Format: The ISO 3166-1 alpha-2 country code. Example: United States is US. |
| CountrySubdivision | The report country subdivision. Format: ISO 3166-2:2007 country subdivision. |
| ProcessingPaymentDate | The date that the report completed all approvals and was ready to be extracted for payment. Format: YYYY-MM-DD |
| ReceiptsReceived | If Y, then this report has its receipt receipt confirmed by the Expense Processor. Format: Y/N |
| ReportOwner | This parent element includes details about the employee who is the report owner. It saves the caller from calling the Get User Information function to get employee information commonly used in accounting integration. The ReportOwner element includes the most recent information about the report owner, at the time the report is requested. |
| EmployeeBankAccount | This parent element includes the bank account data found on the Bank Information page in Profile. This data is used in Payment System integrations where the payment system reimburses the employee via this bank account. |
ExpenseEntry
| Element | Description |
|---|---|
| ReportEntryID | The ID of the report entry. Maximum 13 characters. |
| ExpenseTypeID | The expense type ID for the expense entry. Expense Type IDs are returned in the ExpKey element by the Get Expense Group Configuration endpoint. |
| ExpenseTypeName | The expense type name. Maximum 64 characters. |
| SpendCategory | The spend category specified for this expense type. Varies by client, used in reporting. |
| PaymentTypeCode | The code for the payment type. Maximum 4 characters. |
| PaymentTypeName | The name for the payment type. Maximum 80 characters. |
| TransactionDate | The date of the expense entry. Maximum 10 characters. Format: YYYY-MM-DD |
| TransactionCurrencyName | The name of the transaction currency. Example: US, Dollar |
| ExchangeRate | The exchange rate that applies to the entry. Maximum 23 characters. |
| TransactionAmount | The amount of the expense entry in the original transaction currency. Maximum 23 characters. |
| PostedAmount | The amount of the expense entry in the user's reimbursement currency. The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters. |
| ApprovedAmount | The approved amount of the expense entry in the user's reimbursement currency.The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters. |
| BusinessPurpose | The text from the Business Purpose field of the entry. Maximum 64 characters. |
| VendorDescription | The vendor name of the expense entry, which can be entered manually by the user or imported from the card transaction Merchant Name field. Maximum 64 characters. |
| LocationName | The location for the expense entry, usually the city name. |
| LocationSubdivision | The location's State, Province, or Country Subdivision. Maximum 6 characters. |
| LocationCountry | The location's Country. Maximum 2 characters. |
| OrgUnit1 through OrgUnit6 | The details from the Org Unit custom fields. These may not have data, depending on configuration. Maximum 48 characters for each field. |
| Custom1 through Custom40 | The details from the Custom fields. These may not have data, depending on configuration. Refer to the Custom Fields elements table for more information. |
| FormID | The ID for the expense entry form. |
| EntryImageID | The unique identifier for the image associated with the entry. |
| HasVat | Whether the entry contains VAT data. Maximum 1 character. Format: Y/N |
| HasComments | Whether the expense entry has comments. Maximum 1 character. Format: Y/N |
| CommentCount | The number of comments associated with the expense entry. |
| IsItemized | Whether the expense entry is itemized. Maximum 1 character. Format: Y/N |
| HasExceptions | Whether the expense entry has exceptions. Maximum 1 character. Format: Y/N |
| IsPersonal | Whether the expense entry is marked as personal. Maximum 1 character. Format: Y/N |
| HasAttendees | Whether the expense entry has attendees. Maximum 1 character. Format: Y/N |
| HasAllocation | Defines the amount of allocations for the expense. Maximum 1 character. Possible values are: P, for partial allocation, F, for full allocation, or N, for no allocation. |
| IsCreditCardCharge | Whether the expense came from a credit card feed. Maximum 1 character. Format: Y/N |
| IsPersonalCardCharge | Whether the expense came from a personal card feed. Maximum 1 character. Format: Y/N |
| ReceiptRequired | Whether the original receipt is required for the entry. Maximum 1 character. Format: Y/N |
| ImageRequired | Whether a receipt image is required for the entry. Maximum 1 character. Format: Y/N |
| E-ReceiptID | The ID for the attached e-receipt, if available. |
| LastModifiedDate | The date the expense entry was last changed. Maximum 19 characters. Format: YYYY-MM-DDThh:mm:ss |
| ItemizationsList | The list of itemizations for the expense entry. This parent element will have at least one Itemization child element. If the expense entry is not itemized, the Itemization will contain the same values as the entry. If the expense entry has itemizations, there will be one Itemization child element for each itemization. Refer to the Itemization elements table for more information. NOTE: There are a few rare cases where the ItemizationsList will be null. This happens when a report entry has a payment type code that is not IBCP with offsets or CBCP and there is a Regular or Child expense entry with an Approved Amount equal to zero. The expense entry will have a Null ItemizationsList. |
| ReportEntryVendorName | Vendor name the employee selected from the Vendor list field. Maximum 64 characters. |
| ReportEntryReceiptReceived | If Y, then this entry has been marked as reviewed by a processor. Maximum 1 character. Format: Y/N |
| ReportEntryReceiptType | Maximum 1 character. One of these: T = tax receipt R= regular receipt N = no receipt |
| CardTransaction | This parent element includes the card transaction data found in the card transaction associated to this expense entry. This data is used in Payment System integrations where the payment system reimburses the card issuer for the indicated card account. Refer to the CardTransaction elements table. |
| ExpensePay | Whether the entry was paid using the Expense Pay service. This element has a value if the report has reached the Processing Payment workflow step. Format: Yes/No |
Report Details - Itemization
| Element | Description |
|---|---|
| ItemType | The type of itemization. If the expense entry does not have any itemizations, this will be set to Regular. If the expense entry contains itemizations, each one will be set to Child. |
| ItemizationID | The unique identifier for the itemization. Maximum 19 characters. |
| ExpenseTypeID | The expense type ID for the itemization. |
| ExpenseTypeName | The expense type for the itemization. Maximum 64 characters. |
| TransactionDate | The date of the transaction. Maximum 10 characters. Format: YYYY-MM-DD |
| TransactionAmount | The amount for the itemization in the expense currency. Maximum 23 characters. |
| PostedAmount | The amount for the itemization in the user's reimbursement currency. The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters. |
| ApprovedAmount | The approved amount of the itemization in the user's reimbursement currency. The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters. |
| BusinessPurpose | The business purpose field from the report header. |
| OrgUnit1 through OrgUnit6 | The details from the Org Unit custom fields. These may not have data, depending on configuration. Maximum 48 characters for each field. |
| Custom1 through Custom40 | The custom fields associated with the itemization. These may not have data, depending on your configuration. Refer to the Custom Fields elements table for more information. |
| Value | The value in the custom field. Maximum 48 characters. |
| Code | Custom list fields will include the list item code in this element. |
| HasComments | Whether the itemization has comments. Maximum 1 character. Format: Y/N |
| CommentCount | The number of comments associated with the itemization. |
| IsPersonal | Whether the itemization is personal. Maximum 1 character. Format: Y/N |
| LastModified | The UTC date when the itemization was last modified. Maximum 19 characters. Format: YYYY-MM-DDThh:mm:ss |
| AttendeesList | This parent element contains one Attendee element for each associated attendee. Refer to the Attendee elements table for more information. |
| AllocationsList | This parent element contains at least one Allocation element. It will contain multiple Allocation elements if there are multiple allocations for the itemization. Refer to the Allocation elements table. |
Report Details - Attendee
| Element | Description |
|---|---|
| AttendeeType | The type of attendee. Maximum 40 characters. |
| FirstName | The attendee's first name. Maximum 50 characters. |
| LastName | The attendee's last name. Maximum 132 characters. |
| Company | The attendee's company name. Maximum 150 characters. |
| Title | The attendee's title. Maximum 32 characters. |
| ExternalID | The unique identifier for the attendee, managed outside SAP Concur. Maximum 48 characters. |
| Custom1 through Custom20 | The details from the custom fields. These may not have data, depending on configuration. Refer to the Custom Fields elements table for more information. |
| HasExceptionsPrevYear | Whether the attendee has exceptions in the previous year, based on yearly total limits for attendees. Maximum 1 character. Format: Y/N |
| HasExceptionsYTD | Whether the attendee has exceptions in the current year, based on yearly total limits for attendees. Maximum 1 character. Format: Y/N |
| IsDeleted | Whether the attendee is marked as deleted. Maximum 1 character. Format: Y/N |
| OwnerName | The name of the employee that owns the attendee record. |
| TotalAmountPrevYear | The total amount spent on the attendee in the previous calendar year. |
| TotalAmountYTD | The total amount spent on the attendee in the current calendar year. |
| VersionNumber | The attendee's version number. |
| AttendeeID | Attendee unique identifier within SAP Concur. |
| AttendeeTypeCode | The unique identifier for the attendee type. |
| AttendeeOwnerID | The unique identifier for the person or system that owns the attendee. |
| CurrencyCode | The 3-letter ISO 4217 currency code for attendee related amounts. |
Report Details - Allocation
| Element | Description |
|---|---|
| AllocationID | The unique alphanumeric identifier for the allocation. Maximum 13 characters. |
| Percentage | The percentage of the expense that is included in this allocation. Maximum 11 characters. |
| AccountCode1 | The primary accounting code assigned to the expense type associated with this allocation. Typically, expense types have only this primary account code. |
| AccountCode2 | The secondary or alternative accounting code assigned to the expense type associated with this allocation. In rare cases some expense types include this accounting code to handle special cases. One example of these special cases is when using travel allowance, where one expense would use the primary account code for the allowed amount, and the alternative account code for the overage. Another example is personal use of a company car. Refer to the Expense: Account Codes Setup Guide for more information on how Concur Expense determines which accounting codes to use. |
| Custom1 through Custom20 | The custom fields associated with the allocation. These may not have data, depending on your configuration. Refer to the Custom Fields elements table for more information. |
| JournalEntriesList | This parent element contains at least one JournalEntry child element. It contains multiple JournalEntry elements if the allocation has multiple journal entries. Refer to the JournalEntry elements table for more information. |
| VATDataList | This parent element contains one VATData element for each VAT line item. This element will be empty if there are no VAT line items. Refer to the VATData elements table for more information. |
JournalEntry
| Element | Description |
|---|---|
| JournalID | Unique identifier for the journal entry. |
| PayerPaymentTypeName | Payer payment type. Maximum 64 characters. One of these: Company = Company Employee = Employee Payment Type for the Credit Card Payment Type |
| PayerPaymentTypeCode | Payment code name for the payer. Maximum 80 characters. |
| PayeePaymentTypeName | Payee payment type. Maximum 64 characters. One of these: Company = Company Employee = Employee Payment Type for the Credit Card Payment Type |
| PayeePaymentCode | Payment code name for the payee. Maximum 80 characters. |
| AccountCode | The account code Concur Expense determines should apply to this journal entry. For journal entries associated to an allocation, Concur Expense uses the business logic described in the Expense: Account Codes Setup Guide to determine whether the primary or secondary account code should apply. When there is no allocation associated to the journal entry, Concur Expense uses clearing account codes for Credit Card and Cash Advance for personal use of a company paid expense or a cash advance issued to an employee respectively. Maximum 48 characters. NOTE: The developer should almost always use this accounting code when creating financial transactions in financial systems. In some situations a developer may need to use the accounting codes in the Allocation parent element. |
| DebitOrCredit | Maximum 2 characters. Either: DR = Debit CR = Credit |
| Amount | Value, as credit or debit, of the amount to be exchanged between the payer and payee for this expense account code (not an absolute value) Maximum 23 characters. EXAMPLES: Value of zero, credit, or debit, as the following: 0 (Zero) "0" + (Plus / Debit) "+50.00" - (Minus / Credit) "-50.00" |
| JobRunKey | Either the unique identifier for job run for the accounting extract that processed this journal, or a static value indicating the journal was processed by Manual Pay, Expense Pay, or some other system. |
VATData
| Element | Description |
|---|---|
| TaxName | Tax authority name. Maximum 50 characters. |
| TaxAuthorityLabel | 5-digit code that appears on the expense entry pages. Maximum 5 characters. |
| TaxTransactionAmount | Calculated tax amount for this expense in the spend currency. Maximum 23 characters. |
| TaxPostedAmount | Calculated tax amount for this expense entry in the reimbursement currency. Maximum 23 characters. |
| Source | Specifies how the tax data was derived. Maximum 4 characters. One of these: CARD = Provided from company card USER = Entered by employee SYST = Calculated by system PROC = Entered by processor |
| TaxReclaimTransactionAmount | Calculated amount of tax eligible for reclaim in the spend currency. Maximum 23 characters. |
| TaxReclaimPostedAmount | Calculated amount of tax eligible for reclaim in the reimbursement currency. Maximum 23 characters. |
CardTransaction
| Element | Description |
|---|---|
| AccountNumber | Credit card number used for this expense. This value is encrypted in the response. Maximum 255 characters. |
| CardDescription | The name on the credit card used for this expense. Maximum 255 characters. |
| CardTypeCode | Type of credit card. |
| TransactionReferenceNumber | Reference number from the credit card vendor. Maximum 64 characters. |
| TransactionCCTType | Transaction type supplied by card vendor. Maximum 3 characters. One of these: ANF = Annual Fees CAV = Cash Advance CCF = Cash and Check Fees CHG = Other Bank Charges and Fees FNC = Finance Charges LAF = Late Fees NSF = Insufficient Funds Check Fees PAY = Payment RPE = Credit Card Transaction |
| TransactionID | Calculated value assigned to this card entry during the import process. Maximum 32 characters. |
| TransactionAmount | Amount of the charge in the spend currency. Maximum 23 characters. |
| TaxAmount | Amount of tax on the transaction amount (if provided by card vendor). Maximum 23 characters. |
| TransactionAlphaCode | Currency code for the spend currency. Maximum 3 characters. Format: ISO 4217 3 digit alpha code |
| PostedAmount | Amount of the charge in the billing currency of the card. Maximum 23 characters. |
| PostedAlphaCode | Currency code for the card billing currency. Maximum 3 characters. Format: ISO 4217 3 digit alpha code |
| TransactionDate | Date the charge was made at the merchant. Maximum 10 characters. |
| PostedDate | Date the charge was posted to the credit card account. Maximum 10 characters. |
| Description | Description of the charge from the merchant. Maximum 42 characters. |
| MasterCardCode | Merchant code sent from the credit card vendor. Maximum 5 characters. |
| TransactionMerchantName | Name of the merchant. Maximum 50 characters. |
| MerchantCity | Merchant city. Maximum 40 characters. |
| MerchantState | Merchant State/Province. Maximum 32 characters. |
| MerchantCountryCode | Merchant country location code. Format: 2 digit alpha code |
| MerchantReferenceNumber | Merchant reference number passed from the merchant to the card. Maximum 15 characters. |
| ExchangeRateFromBillingToEmployeeCurrency | Currency exchange rate used between the credit card billing currency and the employee's reimbursement currency. Maximum 23 characters. |
| BillingAmount | Amount due to the company card from the employee or company (depending on who is responsible for the bill) for this detail row. Maximum 23 characters. |
| AccountNumberLastSegment | The last 4 digits of the Card Account. |
Custom Fields
| Element | Description |
|---|---|
| Type | The custom field type. Will be one of the following: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text |
| Value | The value in the custom field. Maximum 48 characters. |
| Code | Custom list fields will include the list item code in this element. |
ReportOwner
| Element | Description |
|---|---|
| EmployeeCustom21 | The report owner's group ID. Maximum 48 characters. |
| EmployeeID | Employee ID often also serves as the employee's Vendor ID for AP system integrations or Payroll ID for Payroll integrations. Maximum 48 characters. |
| EmployeeOrgUnit1 through EmployeeOrgUnit6 | The report owner's organizational unit information. Maximum 48 characters for each field. |
| FirstName | The report owner's first name. Maximum 32 characters. |
| LastName | The report owner's last name. Maximum 32 characters. |
| MiddleInitial | The report owner's middle initial. Maximum 1 character. |
| ReimbursementMethodCode | The report owner's reimbursement method code, as defined in the employee's Profile. |
EmployeeBankAccount
| Element | Description |
|---|---|
| BankNumber | The bank identification number entered on the Bank Information page. Maximum 11 characters. |
| BankName | The bank name entered on the Bank Information page. Maximum 48 characters. |
| BranchLocation | The branch location entered on the Bank Information page. Maximum 30 characters. |
| AccountNumber | The bank account number entered on the Bank Information page. Maximum 100 characters. |
| AccountName | The name on the account entered on the Bank Information page. |
| PostalAddressLine1 | The postal address line 1 entered on the Bank Information page. Maximum 48 characters. |
| PostalAddressLine2 | The postal address line 2 entered on the Bank Information page. Maximum 48 characters. |
| PostalAddressCity | The postal address city entered on the Bank Information page. Maximum 24 characters. |
| PostalAddressRegion | The postal address region entered on the Bank Information page. Maximum 24 characters. |
| PostalAddressCode | The postal address code entered on the Bank Information page. Maximum 20 characters. |
| PostalAddressCountry | The postal address country entered on the Bank Information page. Maximum 2 characters. Format: The ISO 3166-1 alpha-2 country code. Example: United States is US. |
Report Details - Examples
XML Example Request
GET https://www.concursolutions.com/api/expense/expensereport/v2.0/report/n6ujbuLd1Arwe45lT7As3ThJYJf2dAsrrEW HTTP/1.1
Authorization: OAuth {access token}
...
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
<?xml version="1.0" encoding="utf-8"?>
<ReportDetails xmlns="http://www.concursolutions.com/api/expense/expensereport/2012/07" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<UserLoginID>cm@example.com</UserLoginID>
<EmployeeName>Miller, Chris</EmployeeName>
<ReportID>425FE2ADB4954FCA90CD</ReportID>
<ReportName>Client Meeting</ReportName>
<Purpose>Sales meeting</Purpose>
<ReportDate>2013-01-10T00:00:00</ReportDate>
<CreationDate>2013-01-11T01:58:20</CreationDate>
<SubmitDate>0001-01-01T00:00:00</SubmitDate>
<PaidDate i:nil="true" />
<CurrencyCode>USD</CurrencyCode>
<ReportTotal>50.00000000</ReportTotal>
<PersonalExpenses>0.00000000</PersonalExpenses>
<AmountDueEmployee>50.00000000</AmountDueEmployee>
<AmountDueCompanyCard>0.00000000</AmountDueCompanyCard>
<TotalClaimedAmount>50.00000000</TotalClaimedAmount>
<TotalApprovedAmount>50.00000000</TotalApprovedAmount>
<ApprovalStatusCode>A_NOTF</ApprovalStatusCode>
<ApprovalStatusName>Not Submitted</ApprovalStatusName>
<PaymentStatusCode>P_NOTP</PaymentStatusCode>
<PaymentStatusName>Not Paid</PaymentStatusName>
<OrgUnit1>Sales</OrgUnit1>
<OrgUnit2 />
<OrgUnit3 />
<OrgUnit4 />
<OrgUnit5 />
<OrgUnit6 />
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<LedgerName>Corporate</LedgerName>
<PolicyID>ndrF8hjzl9FtFUdfaBwVvXP$sD1vDpRKNf</PolicyID>
<EverSentBack>N</EverSentBack>
<HasException>N</HasException>
<WorkflowActionURL />
<ExpenseEntriesList>
<ExpenseEntry>
<ReportEntryID>nE0avYnILN9mHdTErNSd2pH45udFoNQ$po</ReportEntryID>
<ExpenseTypeID>BUSML</ExpenseTypeID>
<ExpenseTypeName>Business Meal (attendees)</ExpenseTypeName>
<SpendCategory>Entertainment</SpendCategory>
<PaymentTypeCode>CASH</PaymentTypeCode>
<PaymentTypeName>Cash</PaymentTypeName>
<TransactionDate>2013-01-10T00:00:00</TransactionDate>
<TransactionCurrencyName>US, Dollar</TransactionCurrencyName>
<ExchangeRate>1.00000000000000</ExchangeRate>
<TransactionAmount>50.00000000</TransactionAmount>
<PostedAmount>50.00000000</PostedAmount>
<ApprovedAmount />
<BusinessPurpose />
<VendorDescription />
<LocationName>Washington</LocationName>
<LocationSubdivision>US-DC</LocationSubdivision>
<LocationCountry>US</LocationCountry>
<OrgUnit1>Sales</OrgUnit1>
<OrgUnit2 />
<OrgUnit3 />
<OrgUnit4 />
<OrgUnit5 />
<OrgUnit6 />
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<Custom21 />
<Custom22 />
<Custom23 />
<Custom24 />
<Custom25 />
<Custom26 />
<Custom27 />
<Custom28 />
<Custom29 />
<Custom30 />
<Custom31 />
<Custom32 />
<Custom33 />
<Custom34 />
<Custom35 />
<Custom36 />
<Custom37 />
<Custom38 />
<Custom39 />
<Custom40 />
<FormID>nAaT8$puKKOhs7h2wespCW7vyyxJAJcyb5</FormID>
<EntryImageID />
<HasVat>N</HasVat>
<HasComments>N</HasComments>
<CommentCount>0</CommentCount>
<IsItemized>Y</IsItemized>
<HasExceptions>N</HasExceptions>
<IsPersonal>N</IsPersonal>
<HasAttendees>Y</HasAttendees>
<HasAllocation>N</HasAllocation>
<IsCreditCardCharge>N</IsCreditCardCharge>
<IsPersonalCardCharge>N</IsPersonalCardCharge>
<ReceiptRequired>N</ReceiptRequired>
<ImageRequired>N</ImageRequired>
<E-ReceiptID />
<LastModified>2013-01-11T01:59:52</LastModified>
<ItemizationsList>
<Itemization>
<ItemType>Regular</ItemType>
<ItemizationID>nE0avYnILN9mHdTErNSd2pH45udFoNQ$po</ItemizationID>
<ExpenseTypeID>BUSML</ExpenseTypeID>
<ExpenseTypeName>Business Meal (attendees)</ExpenseTypeName>
<TransactionDate>2013-01-10T00:00:00</TransactionDate>
<TransactionAmount>50.00000000</TransactionAmount>
<PostedAmount>50.00000000</PostedAmount>
<ApprovedAmount />
<BusinessPurpose />
<OrgUnit1>Sales</OrgUnit1>
<OrgUnit2 />
<OrgUnit3 />
<OrgUnit4 />
<OrgUnit5 />
<OrgUnit6 />
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<Custom21 />
<Custom22 />
<Custom23 />
<Custom24 />
<Custom25 />
<Custom26 />
<Custom27 />
<Custom28 />
<Custom29 />
<Custom30 />
<Custom31 />
<Custom32 />
<Custom33 />
<Custom34 />
<Custom35 />
<Custom36 />
<Custom37 />
<Custom38 />
<Custom39 />
<Custom40 />
<HasComments>N</HasComments>
<CommentCount>0</CommentCount>
<IsPersonal>N</IsPersonal>
<LastModified>2013-01-11T01:59:52</LastModified>
<AllocationsList />
<AttendeesList>
<Attendee>
<AttendeeType>BUSGUEST</AttendeeType>
<FirstName>Pat</FirstName>
<LastName>Davis</LastName>
<Company />
<Title />
<ExternalID />
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<HasExceptionsPrevYear>N</HasExceptionsPrevYear>
<HasExceptionsYTD>N</HasExceptionsYTD>
<IsDeleted>N</IsDeleted>
<OwnerEmpName>Miller, Chris</OwnerEmpName>
<TotalAmountPrevYear>0.00000000</TotalAmountPrevYear>
<TotalAmountYTD>0.00000000</TotalAmountYTD>
<VersionNumber>1</VersionNumber>
<AttendeeID>nFaAj038Hw$plfUD8be0I45wTx8$sMlTd$pP</AttendeeID>
<AttendeeTypeCode>BUSGUEST</AttendeeTypeCode>
<AttendeeOwnerID>cm@example.com</AttendeeOwnerID>
<CurrencyCode>USD</CurrencyCode>
</Attendee>
</AttendeesList>
</Itemization>
<Itemization>
<ItemType>Child</ItemType>
<ItemizationID>nE0avYnILN9g$s6lCFX0jFBWmHAiTYYf9C</ItemizationID>
<ExpenseTypeID>BRKFT</ExpenseTypeID>
<ExpenseTypeName>Breakfast</ExpenseTypeName>
<TransactionDate>2013-01-10T00:00:00</TransactionDate>
<TransactionAmount>50.00000000</TransactionAmount>
<PostedAmount>50.00000000</PostedAmount>
<ApprovedAmount>50.00000000</ApprovedAmount>
<BusinessPurpose />
<OrgUnit1>Sales</OrgUnit1>
<OrgUnit2 />
<OrgUnit3 />
<OrgUnit4 />
<OrgUnit5 />
<OrgUnit6 />
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<Custom21 />
<Custom22 />
<Custom23 />
<Custom24 />
<Custom25 />
<Custom26 />
<Custom27 />
<Custom28 />
<Custom29 />
<Custom30 />
<Custom31 />
<Custom32 />
<Custom33 />
<Custom34 />
<Custom35 />
<Custom36 />
<Custom37 />
<Custom38 />
<Custom39 />
<Custom40 />
<HasComments>N</HasComments>
<CommentCount>0</CommentCount>
<IsPersonal>N</IsPersonal>
<LastModified>2013-01-11T01:59:52</LastModified>
<AllocationsList>
<Allocation>
<AllocationID>ngYn5SB4OUXgRV6P8VgsQQr88SaKYvbqz</AllocationID>
<Percentage>100.00000000%</Percentage>
<AccountCode1>AC_BRKFT1</AccountCode1>
<AccountCode2>AC_BRKFT2</AccountCode2>
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<VATDataList />
</Allocation>
</AllocationsList>
<AttendeesList />
</Itemization>
</ItemizationsList>
<UserLoginID>cm@example.com</UserLoginID>
</ExpenseEntry>
</ExpenseEntriesList>
<Country>US</Country>
<CountrySubdivision></CountrySubdivision>
<ProcessingPaymentDate></ProcessingPaymentDate>
<ReceiptsReceived>Y</ReceiptsReceived>
<ReportOwner>
<EmployeeID>cm@example.com</EmployeeID>
<LastName>Chris</LastName>
<FirstName>Miller</FirstName>
<MiddleInitial></MiddleInitial>
<EmployeeCustom21></EmployeeCustom21>
<EmployeeOrgUnit1></EmployeeOrgUnit1>
<EmployeeOrgUnit2></EmployeeOrgUnit2>
<EmployeeOrgUnit3></EmployeeOrgUnit3>
<EmployeeOrgUnit4></EmployeeOrgUnit4>
<EmployeeOrgUnit5></EmployeeOrgUnit5>
<EmployeeOrgUnit6></EmployeeOrgUnit6>
<ReimbursementMethodCode>CNQRPAY</ReimbursementMethodCode>
</ReportOwner>
</ReportDetails>
Payment Batches
The Payment Batch File web service provides an automated solution to clients who would like to manage their payment batches and collect their batch files.
- Retrieve the list of payment batches
- Close a payment batch asynchronously
- Close a payment batch synchronously
- Retrieve a payment batch file
- Error Messages
Process Flow

Product and Edition
Concur Expense Standard Edition
NOTE: For Concur Expense Professional Edition, use Extracts v1 API
Retrieve the List of Payment Batches
Retrieves the list of payment batches with an optional requested status.
GET /api/expense/paymentbatch/v1.1/batchlist/
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
batchlist |
string |
- | Required. The batchlist keyword. |
Status |
Boolean |
- | The status of the batches. Can be either OPEN or CLOSED. |
Retrieve Payment Batches Response Schema
| Name | Type | Format | Description |
|---|---|---|---|
BatchName |
string |
- | The batch name, as it appears in Payment Manager. |
BatchID |
string |
- | The unique identifier for the batch. |
BatchTotal |
Decimal |
- | The batch total amount. |
Currency |
string |
- | The 3-letter ISO 4217 currency code for the batch. |
Count |
string |
- | The number of payment demands in the batch. |
Type |
string |
- | The payee of the batch. Either Employee or Card Program. |
PaymentMethod |
string |
- | The reimbursement method for the batch. Either Expense Pay by SAP Concur, Company Check (via Accounts Payable), ADP (via EPIP file), or Other Reimbursement Methods. |
Batch-URL |
string |
- | The URL to use as a basis for other actions, such as closing the batch. |
Close a Payment Batch Asynchronously
Version 1.2
This asynchronous request schedules closing of the specified batch, preventing any new expenses from entering it. After the batch closes, you can use Close Payment Batch v1.1 to get the File-Url to download the file containing the expense transaction information.
Note: You can check batch status using the Retrieve the List of Payment Batches method.
POST /api/expense/paymentbatch/v1.2/batch/{BatchID}/close
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
BatchID |
string |
- | Required. The unique identifier for the batch. |
close |
string |
- | Required. The close keyword. |
Close Payment Batch Asynchronously Response Schema
| Name | Type | Format | Description |
|---|---|---|---|
Status |
string |
- | The status of the request to close the batch. |
JobQueueKey |
string |
- | The unique identifier for the batch job. |
Close a Payment Batch Synchronously
Version 1.1
This request synchronously closes the batch preventing any new expenses from entering it. After the batch closes, SAP Concur creates the batch file containing the expense transaction information. If a batch ID for an already closed batch is sent, SAP Concur regenerates the batch file for the specified batch.
This synchronous call has a time limit that can be superseded by the time it takes to close the batch. It is recommended that you use Close a Payment Batch Asynchronously (v1.2) to close batches, then use this request after the batch is closed to obtain the File-Url needed to download the file with the expense transaction information.
Note: You can check batch status using the Retrieve the List of Payment Batches method.
POST /api/expense/paymentbatch/v1.1/batch/{BatchID}/close
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
BatchID |
string |
- | Required. The unique identifier for the batch. |
close |
string |
- | Required. The close keyword. |
Close Payment Batch Synchronously Response Schema
| Name | Type | Format | Description |
|---|---|---|---|
BatchStatus |
string |
- | The current status of the specified batch. |
File-Url |
string |
- | A URL for retrieving the extract file or files produced when the batch closes, with encrypted ID. |
Status |
string |
- | The status of the request to close the batch. |
Retrieve a Payment Batch File
Requests the expense transaction data for the specified payment batch.
GET /api/expense/paymentbatch/v1.1/batch/{JobRunKey}/file
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
JobRunKey |
string |
- | Required. The File-Url element returned by the Close Batches 1.1 API response contains the encrypted JobRunKey. In practice, you can use the File-Url whole value to download the file. |
Retrieve Payment Batch File Response Schema
This request will return the expense transaction data in text/csv format if there was a single file produced or as a zip archive if the batch is configured to produce more than one file. An example of a client who will receive multiple files is a client using QuickBooks, who receives one file formatted for import into QuickBooks (.IIF extension), and one file for the general ledger (.CSV extension), inside a .ZIP file.
Error Messages
| Error Number | Description |
|---|---|
500 |
The batch you attempted to close does not contain any reports. If you recently approved reports for payment, wait 30 minutes and try again. |
Enterprise Resource Planning Integration
Before you begin, you need to close the Payment Manager batch in order for you to retrieve the files using this API. Ask your client not to close the batch manually through the user interface.
- Obtain a list of your client’s batches by using Get list of batches
- Close the desired batch by using Close a payment batch
- Retrieve the file you want by using Retrieve a payment batch file
Quick Expense v4
The Quick Expense API can be used to create an expense with basic information such as date, amount, and expense type, with or without a receipt image. This expense can be added to an expense report within Concur Expense, allowing the user to provide additional details such as attendees, itemizations etc.
Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API. This API is not available in Implementation environments.
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Create a Quick Expense
- Create a Quick Expense with an Image
- Schema
Quick Expense - Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
Quick Expense - Scope Usage
Required Scopes:
| Name | Description | Endpoint |
|---|---|---|
quickexpense.writeonly |
Write quick expense. | POST |
user.read |
Get User Information, necessary for userID. |
POST |
receipts.writeonly |
Required if e-Bunsho is enabled Write quick expense. | POST |
Optional Scope:
| Name | Description | Endpoint |
|---|---|---|
CONFIG |
Get Expense Configuration information, necessary for expenseTypeId. |
POST |
Quick Expense - Dependencies
SAP Concur clients must purchase Concur Expense in order to use this API. This API requires the User v3.1 API which is currently only available to approved early access partners. Please contact your SAP Concur representative for more information.
The partner may use the following SAP Concur APIs to get optional information:
* Expense Group Configurations v3.0, to retrieve the expenseTypeId
* Locations v3.0, to retrieve the location id
Japan Market: If the partner is using this API to provide the e-Bunsho digital timestamp for the receipt, the partner should confirm that the client has e-Bunsho activated in SAP Concur.
Quick Expense - Access Token Usage
This API supports both company level and user level access tokens.
Create a Quick Expense
Creates a quick expense without an image.
Scopes
quickexpense.writeonly - Refer to Scope Usage for full details.
Request
URI
Template
https://{datacenterURI}/quickexpense/v4/users/{userID}/context/{contextType}/quickexpenses
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
userID |
string |
- | Required The unique identifier of the SAP Concur user. Use User Profile v1.0 to retrieve the userID. |
contextType |
string |
- | Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported value: TRAVELER. |
Headers
- RFC 7231 Accept-Language
- RFC 7231 Content-Type
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the Company or User access token.
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Response
Status Codes
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Example
Request
curl -X POST \
https://us.api.concursolutions.com/quickexpense/v4/users/184dd31a-f48a-4103-879f-c8d45456c7cd/context/TRAVELER/quickexpenses \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
-H 'concur-correlationid: quick-expense-test' \
-d '{
"comment": "Offsite team lunch.",
"expenseTypeId": "BUSML",
"entryDetails": "test-entry",
"location": {
"city": "Bellevue",
"countryCode": "US",
"countrySubDivisionCode": "US-WA",
"id": "",
"name": ""
},
"paymentTypeId": "CASHX",
"transactionAmount": {
"currencyCode": "USD",
"value": 88.05
},
"transactionDate": "2019-02-04"
}'
Response
201 Created
{
"quickExpenseIdUri": "https://seapr1qes.concurasp.com/quickexpense/v4/users/184dd31a-f48a-4103-879f-c8d45456c7cd/context/TRAVELER/quickexpenses/E018795D2B09094FBF223E209E921B88"
}
Create a Quick Expense with an Image
Creates a quick expense with an image.
Scopes
quickexpense.writeonly - Refer to Scope Usage for full details.
receipts.writeonly - Refer to Scope Usage for full details.
Request
URI
Template
https://{datacenterURI}/quickexpense/v4/users/{userID}/context/{contextType}/quickexpenses/image
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
userID |
string |
- | Required The unique identifier of the SAP Concur user. Use User Profile v1.0 to retrieve the userID. |
contextType |
string |
- | Required The access level of the SAP Concur user, which determines the form fields they can view/modify. Supported values: TRAVELER. |
fileContent |
file |
- | Required The quick expense image. Maximum size 5 MBs. Supported image types are: PNG, PDF, TIFF, JPEG |
Headers
- RFC 7231 Accept-Language
- RFC 7231 Content-Type
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the Company or User access token.
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Response
Status Codes
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Example
Request
curl -X POST \
https://us.api.concursolutions.com/quickexpense/v4/users/184dd31a-f48a-4103-879f-c8d45456c7cd/context/TRAVELER/quickexpenses/image \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: multipart/form-data' \
-H 'concur-correlationid: quick-expense-with-image' \
-H 'content-type: multipart/form-data' \
-F fileContent=@/Users/i845500/Pictures/Snip20180410_1.png \
-F 'quickExpenseRequest={
"comment": "Offsite team lunch.",
"expenseTypeId": "BUSML",
"entryDetails": "test-entry",
"location": {
"city": "Bellevue",
"countryCode": "US",
"countrySubDivisionCode": "US-WA",
"id": "",
"name": ""
},
"paymentTypeId": "CASHX",
"transactionAmount": {
"currencyCode": "USD",
"value": 88.05
},
"transactionDate": "2019-02-04"
}'
Response
201 Created
{
"quickExpenseIdUri": "https://seapr1qes.concurasp.com/quickexpense/v4/users/184dd31a-f48a-4103-879f-c8d45456c7cd/context/TRAVELER/quickexpenses/A0D1CE97B4692B4F8E29BEA53B250E36"
}
Quick Expense - Schema
Quick Expense Request
| Name | Type | Format | Description |
|---|---|---|---|
comment |
string |
- | This is a comment attached to the quick expense. |
entryDetails |
string |
- | The quick expense entry details. |
expenseTypeId |
string |
- | Required This is the expense type id of quick expense. Use Expense Group Configurations v3.0 to retrieve the supported expense types. Supported values for a null value are: UNDEF, NULL. NULL can only be used on a POST operation and will be converted to UNDEF. |
location |
- | Location | The location where the quick expense occurred. |
paymentTypeId |
string |
- | This is the payment type id of quick expense. Supported values: CASHX, CPAID, PENDC. |
transactionAmount |
- | Amount | Required The amount of the quick expense. |
transactionDate |
string |
YYYY-MM-DD | Required This is the transaction date of the quick expense. |
vendor |
string |
- | The name of the vendor. |
Location
| Name | Type | Format | Description |
|---|---|---|---|
city |
string |
- | The location city. |
countryCode |
string |
- | The location country ISO 3166-1 code. |
countrySubDivisionCode |
string |
- | The location country sub division ISO 3166-2 code. |
id |
string |
- | The unique identifier of the location. Use Locations v3.0 to retrieve the location id. |
name |
string |
- | The location name. |
Amount
| Name | Type | Format | Description |
|---|---|---|---|
currencyCode |
string |
- | Required The 3-letter ISO 4217 currency code. |
value |
number |
- | Required The amount value. |
Quick Expense Response
| Name | Type | Format | Description |
|---|---|---|---|
quickExpenseIdUri |
string |
- | The quick expense created resource url. |
Quick Expense - Error
| Name | Type | Format | Description |
|---|---|---|---|
errorId |
string |
- | The unique identifier of the error. |
errorMessage |
string |
- | Required Message associated with the error. |
httpStatus |
string |
- | The HTTP status associated with the error. |
path |
string |
- | The path to the resource. |
timestamp |
string |
- | The timestamp for the error. |
validationErrors |
array |
validationErrors | An array of validation errors. |
Validation Errors
| Name | Type | Format | Description |
|---|---|---|---|
message |
string |
- | The validation error message. |
source |
string |
- | The source of the validation error. |
Financial Integration Service v4
Getting Started - Financial Integration Service v4
The Financial Integration API allows an external system to interact with financial documents generated from SAP Concur, for financial posting into an ERP.
This API provides an automated solution to request available data objects such as approved expense reports, cash advances, and invoices to import to the client internal system, with an opportunity to send posting confirmation back into SAP Concur before the object is locked down and cannot be altered in SAP Concur.
Below are some benefits for using the Financial Integration service:
- Using a modern method, no more handling of flat files.
- Close to real time experience vs. SAP Concur overnight processing.
- 1 to 1 SAP Concur to ERP reconciliation vs. extract batch processing.
- Opportunity to modify and retry before the object is locked in SAP Concur.
- Ensures data sync between systems.
Contents
- Financial Integration Service Use Cases
- Products and Editions
- Scope Usage
- Access Token Usage
- Get Financial Transactions
- Post Financial Transactions Acknowledgements
- Post Financial Transactions Confirmations
- Post Financial Payment Confirmations
- Service Codes
-
- Financial Documents
- FIDocument
- Page Metadata
- Link
- AcknowledgeRequest
- AcknowledgeResponse
- AcknowledgeResponseItem
- Confirmation Request
- Posting Confirmation Request Item
- Posting Documents Details
- System Messages
- Posting Confirmation Response
- PostingConfirmationResponseItem
- Payment Confirmation Request
- Payment Confirmation Request Item
- Payment Documents Details
- Receiver Details
- Clearing Reference Details
- Payment Confirmation Response
- PaymentConfirmationResponseItem
Financial Documents
Financial Integration - Products and Editions
- Concur Expense Professional Edition
- Concur Expense Standard Edition
- Concur Invoice Professional Edition
- Concur Invoice Standard Edition
Financial Integration - Scope Usage
| Name | Description | Endpoint |
|---|---|---|
| FISVC | Read financial transactions and write financial transaction acknowledgements and confirmations. | GET, POST |
Financial Integration - Access Token Usage
This API only supports company-level access tokens.
Get Financial Transactions
The request returns a list of financial documents that are ready to be processed. The request can include parameters to limit the results.
Scopes
FISVC - Refer to Scope Usage for full details.
Request
URI
Template
https://{datacenterURI}/financialintegration/fi/v4/companies/transactiontypes/{docType}/transactions
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
docType |
string |
path |
Required The financial document type to return. Only one type of transaction can be retrieved at a time. Supported values are: expense, invoice, cashadvance, payroll, obligation. |
page |
int32 |
query |
Starting page number. |
limit |
int32 |
query |
Number of records to return per page (default 25). |
docId |
string |
query |
The transaction unique identifier, it could be expense report ID, payment request ID or cash advance ID. If specified, a single document that matches docId is returned. |
ignoreDocumentStatus |
string |
query |
Ignores the financial documents status. Supported values are: yes or no. If yes, a document is returned regardless of status. If no, only documents that have not been acknowledged/confirmed are returned. |
systemId |
string |
query |
The external system ID that processed the document. Maximum 50 characters. |
Headers
- DocumentFormatAs: Value can be text or json. This determines the document format that's returned from the API.
- RFC 7235 Authorization - Bearer token that identifies the caller. This is the Company access token.
Payload
None.
Response
Status Codes
Headers
concur-correlationidis an SAP Concur specific custom header used for technical support in the form of a RFC 4122 universally unique identifier (UUID) URN Namespace.- RFC 7231 Content-Type
- RFC 7230 Content-Length
Payload
Example
Request
GET https://us.api.concursolutions.com/financialintegration/fi/v4/companies/transactiontypes/expense/transactions?limit=3
Authorization: Bearer {token}
Response
200 OK
Content-Type: application/json
Date: {date-requested}
Content-Length: 491
{
"links" : [ {
"rel" : "first",
"href" : "https://fiserviceurlhere/fi/v4/companies/transactiontypes/expense/transactions?limit=3&page=0&size=3",
"hreflang" : null,
"media" : null,
"title" : null,
"type" : null,
"deprecation" : null
}, {
"rel" : "self",
"href" : "https://fiserviceurlhere/fi/v4/companies/transactiontypes/expense/transactions?limit=3&page=0&size=3",
"hreflang" : null,
"media" : null,
"title" : null,
"type" : null,
"deprecation" : null
}, {
"rel" : "next",
"href" : "https://fiserviceurlhere/fi/v4/companies/transactiontypes/expense/transactions?limit=3&page=1&size=3",
"hreflang" : null,
"media" : null,
"title" : null,
"type" : null,
"deprecation" : null
}, {
"rel" : "last",
"href" : "https://fiserviceurlhere/fi/v4/companies/transactiontypes/expense/transactions?limit=3&page=2&size=3",
"hreflang" : null,
"media" : null,
"title" : null,
"type" : null,
"deprecation" : null
} ],
"content" : [ {
"id" : "e7f810cabc8348cdb051dd9431c8cfbb",
"docType" : "expense",
"companyId" : "COMPANY_ID_HERE",
"entityId" : "ENTITY_ID_HERE",
"companyUuid" : "COMPANY_UUID_HERE",
"erpSystemId" : "",
"document" : "{THE_FINANCIAL_DOCUMENT}",
"docStatus" : "READY",
"links" : [ ]
}, {
"id" : "e1500222f16748718fdd2d493ee4c9dd",
"docType" : "expense",
"companyId" : "COMPANY_ID_HERE",
"entityId" : "ENTITY_ID_HERE",
"companyUuid" : "COMPANY_UUID_HERE",
"erpSystemId" : null,
"document" : "{THE_FINANCIAL_DOCUMENT}",
"docStatus" : "READY",
"links" : [ ]
}, {
"id" : "e2135678f16748718fdd2d493ee4c9dd",
"docType" : "expense",
"companyId" : "COMPANY_ID_HERE",
"entityId" : "ENTITY_ID_HERE",
"companyUuid" : "COMPANY_UUID_HERE",
"erpSystemId" : null,
"document" : "{THE_FINANCIAL_DOCUMENT}",
"docStatus" : "READY",
"links" : [ ]
}
],
"page" : {
"size" : 3,
"totalElements" : 8,
"totalPages" : 3,
"number" : 0
}
}
Post Financial Transaction Acknowledgements
Allows an external system to acknowledge that it has successfully retrieved one or more financial transactions from SAP Concur and will begin processing those transactions. The transactions in the POST request are then taken out of the ready queue.
Scopes
FISVC - Refer to Scope Usage for full details.
Request
URI
Template
https://{datacenterURI}/financialintegration/fi/v4/companies/transactiontypes/{docType}/transactions/acknowledgements
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
docType |
string |
path |
Required The financial document type. Only one type of transaction can be acknowledged at a time. Supported values are: expense, invoice, cashadvance, payroll, obligation. |
Headers
- RFC 7235 Authorization - Bearer token that identifies the caller. This is the Company access token.
- RFC 7231 Content-Type
Payload
Response
Status Codes
Headers
concur-correlationidis an SAP Concur specific custom header used for technical support in the form of a RFC 4122 universally unique identifier (UUID) URN Namespace.- RFC 7231 Content-Type
- RFC 7230 Content-Length
Payload
Example
Request
POST https://us.api.concursolutions.com/financialintegration/fi/v4/companies/transactiontypes/expense/transactions/acknowledgements
Authorization: Bearer {token}
Content-Type: application/json
{
"ids": [ "5ab9224e02e840148e7cd7d9e8e72968", "2ac9224e02e840148e7cd7d9e8e12345" ]
}
Response
This response shows both success and failure service code examples.
200 OK
Content-Type: application/json
Date: {date-requested}
Content-Length: 372
[
{
"code": 0,
"docId": "5ab9224e02e840148e7cd7d9e8e72968",
"systemId": null,
"acknowledgeResult": "SUCCESS",
"errorMessage": ""
},
{
"code": 101,
"docId": "2ac9224e02e840148e7cd7d9e8e12345",
"systemId": null,
"acknowledgeResult": "FAILURE",
"errorMessage": "This document was previously acknowledged by SystemId: null."
}
]
Post Financial Transactions Confirmations
Allows financial posting results to be sent to SAP Concur.
Scopes
FISVC - Refer to Scope Usage for full details.
Request
URI
Template
https://{datacenterURI}/financialintegration/fi/v4/companies/transactiontypes/{docType}/transactions/postingconfirmations
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
docType |
string |
path |
Required The financial document type to return. expense, invoice, cashadvance, payroll, obligation. Only one type of transaction can be retrieved at a time. |
confirmationRequest |
- | body | Required The JSON request to be posted. |
Headers
- RFC 7235 Authorization - Bearer token that identifies the caller. This is the Company access token.
- RFC 7231 Content-Type
Payload
Response
Status Codes
Headers
concur-correlationidis an SAP Concur specific custom header used for technical support in the form of a RFC 4122 universally unique identifier (UUID) URN Namespace.- RFC 7231 Content-Type
- RFC 7230 Content-Length
Payload
Example
Request
POST https://us.api.concursolutions.com/financialintegration/fi/v4/companies/transactiontypes/expense/transactions/postingconfirmations
Authorization: Bearer {token}
Content-Type: application/json
{
"systemId":"",
"postingConfirmations":
[
{
"docId":"0c06ab044834454d91f83cbd7b6431d2",
"overallPostingStatusCode":"error",
"postingDocs":[],
"systemMessages":
[
{
"concurTransactionLineItemId":"",
"messageId":"010-CTE-POSTING",
"messageLanguage":"EN",
"messageLongText":"",
"messageShortText":"Expense Report {ReportKey} of system CONCUR could not be posted."
},
{
"concurTransactionLineItemId":"",
"messageId":"003-CC",
"messageLanguage":"EN",
"messageLongText":"",
"messageShortText":"Profit centre /company code assignment is not correct. Check the entry."
}
]
},
{
"docId":"3331dbeb8e2240ffad7ab5b69492722a",
"overallPostingStatusCode":"success",
"postingDocs":
[
{
"companyId":"0100",
"documentNumber":"0123456",
"fiscalYear":"2018",
"paymentRelevantLineItems":[],
"postingDate":"2018-03-02"
},
{
"companyId":"0800",
"documentNumber":"0123478",
"fiscalYear":"2018",
"paymentRelevantLineItems":[],
"postingDate":"2018-03-02"
}
],
"systemMessages":[]
}
]
}
Response
This response shows both success and failure service code examples.
200 OK
Content-Type: application/json
Date: {date-requested}
Content-Length: 405
[
{
"code": 0,
"docId": "0c06ab044834454d91f83cbd7b6431d2",
"systemId": null,
"postingConfirmationResult": "SUCCESS",
"errorMessage": "",
"detailMessage": ""
},
{
"code": 116,
"docId": "3331dbeb8e2240ffad7ab5b69492722a",
"systemId": "",
"postingConfirmationResult": "FAILURE",
"errorMessage": "This document does not exist.",
"detailMessage": ""
}
]
Post Financial Payment Confirmations
Allows financial payment results to be sent to SAP Concur.
Scopes
FISVC - Refer to Scope Usage for full details.
Request
URI
Template
https://{datacenterURI}/financialintegration/fi/v4/companies/transactiontypes/{docType}/transactions/paymentconfirmations
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
docType |
string |
path |
Required The financial document type to return. expense, invoice, cashadvance, payroll, obligation. Only one type of transaction can be retrieved at a time. |
confirmationRequest |
body | Required The JSON request to be posted. |
Headers
- RFC 7235 Authorization - Bearer token that identifies the caller. This is the Company access token.
- RFC 7231 Content-Type
Payload
Response
Status Codes
Headers
concur-correlationidis an SAP Concur specific custom header used for technical support in the form of a RFC 4122 universally unique identifier (UUID) URN Namespace.- RFC 7231 Content-Type
- RFC 7230 Content-Length
Payload
Example
Request
POST https://us.api.concursolutions.com/financialintegration/fi/v4/companies/transactiontypes/expense/transactions/paymentconfirmations
Authorization: Bearer {token}
Content-Type: application/json
{
"systemId":"",
"processingConfirmation":
[
{
"docId":"0c06ab044834454d91f83cbd7b6431d2",
"processingStatusCode":"CP",
"clearingDetails":[
{
"clearingDate":"2019-02-06T12:00:00.27Z","clearingAmount":220.00,
"clearingCurrency":"USD","receiver":{"receiverId":"22344",
"receiverName":"Charles","receiverType":"EMPLOYEE"},
"clearingReference":{"companyCode":"US01","financialDocumentId":"667799",
"fiscalYear":"2019","paymentRef":"US01/667799/2019/2","paymentMethod":"E"}
}
]
},
{
"docId":"454d91f83cbd7b6431d20c06ab044834",
"processingStatusCode":"PP",
"clearingDetails":[
{
"clearingDate":"2019-02-06T12:00:00.27Z","clearingAmount":40.00,
"clearingCurrency":"USD","receiver":{"receiverId":"57",
"receiverName":"John","receiverType":"EMPLOYEE"},
"clearingReference":{"companyCode":"US01","financialDocumentId":"996675",
"fiscalYear":"2019","paymentRef":"US01/996675/2019/2","paymentMethod":"E"}
}
]
},
{
"docId":"1d20c06ab0445d7b64348344d91f83cb",
"processingStatusCode":"PP",
"clearingDetails":[
{
"clearingDate":"2019-02-06T12:00:00.27Z","clearingAmount":23.00,
"clearingCurrency":"USD","receiver":{"receiverId":"57",
"receiverName":"Alice","receiverType":"EMPLOYEE"},
"clearingReference":{"companyCode":"US01","financialDocumentId":"95432",
"fiscalYear":"2019","paymentRef":"US01/95432/2019/2","paymentMethod":"E"}
}
]
},
{
"docId":"d2454d91fcb44834830c06ab0d7b6431",
"processingStatusCode":"RE",
"additionalMessage":"This report was sent to wrong system",
"clearingDetails":[
{
"clearingDate":"2019-02-06T12:00:00.27Z","clearingAmount":10.00,
"clearingCurrency":"USD","receiver":{"receiverId":"57",
"receiverName":"Peter","receiverType":"EMPLOYEE"},
"clearingReference":{"companyCode":"US01","financialDocumentId":"5498",
"fiscalYear":"2019","paymentRef":"US01/5498/2019/2","paymentMethod":"E"}
}
]
},
{
"docId":"b6431d2454dcbd791f44834830c06ab0",
"processingStatusCode":"OB",
"additionalMessage":"Not required anymore",
"clearingDetails":[
{
"clearingDate":"2019-02-06T12:00:00.27Z","clearingAmount":54.00,
"clearingCurrency":"USD","receiver":{"receiverId":"57",
"receiverName":"Kevin","receiverType":"EMPLOYEE"},
"clearingReference":{"companyCode":"US01","financialDocumentId":"32478",
"fiscalYear":"2019","paymentRef":"US01/32478/2019/2","paymentMethod":"E"}
}
]
}
]
}
Response
This response shows both success and failure service code examples.
200 OK
Content-Type: application/json
Date: {date-requested}
Content-Length: 405
[
{
"code" : 0,
"docId" : "0c06ab044834454d91f83cbd7b6431d2",
"systemId" : "",
"paymentConfirmationResult" : "SUCCESS",
"errorMessage" : null,
"paymentRef" : "US01/667799/2019/2",
"detailMessage" : ""
},
{
"code" : 116,
"docId" : "454d91f83cbd7b6431d20c06ab044834",
"systemId" : "",
"paymentConfirmationResult" : "FAILURE",
"errorMessage" : "This document does not exist.",
"paymentRef" : "US01/996675/2019/2",
"detailMessage" : ""
},
{
"code" : 298,
"docId" : "1d20c06ab0445d7b64348344d91f83cb",
"systemId" : "",
"paymentConfirmationResult" : "NOOP",
"errorMessage" : "Payment confirmation already exist US01/95432/2019/2.",
"paymentRef" : "US01/95432/2019/2",
"detailMessage" : ""
}
{
"code" : 0,
"docId" : "d2454d91fcb44834830c06ab0d7b6431",
"systemId" : "",
"paymentConfirmationResult" : "SUCCESS",
"errorMessage" : null,
"paymentRef" : "US01/5498/2019/2",
"detailMessage" : ""
},
{
"code" : 0,
"docId" : "b6431d2454dcbd791f44834830c06ab0",
"systemId" : "",
"paymentConfirmationResult" : "SUCCESS",
"errorMessage" : null,
"paymentRef" : "US01/32478/2019/2",
"detailMessage" : ""
}
]
Service Codes
The Financial Integration Service will return service codes based on the success and failure of individual records for acknowledging and posting confirmation of documents.
| Code | Description | Category |
|---|---|---|
| 0 | Successfully processed | Any |
| 99 | System ID in request does not match system ID in FI database. | Any |
| 101 | This document was previously acknowledged. | Acknowledge |
| 102 | This document has been recalled. | Acknowledge |
| 103 | This document is not ready. | Acknowledge |
| 104 | This document does not exist in the FI database. | Acknowledge |
| 105 | This document is not of type (expense, invoice, cashadvance). | Acknowledge |
| 111 | This document has not been acknowledged. | Posting |
| 112 | This document has been recalled. | Posting |
| 113 | Confirmation has been posted for this document. | Posting |
| 114 | Document is not in a known state. | Posting |
| 115 | This document is not of type (expense, invoice, cashadvance). | Posting |
| 116 | This document does not exist in the FI database. | Posting |
| 198 | Invalid request - this same request will not work if tried again. | Posting |
| 199 | Unknown error, please try again later. | Any |
Financial Integration - Schema
Financial Documents
| Name | Type | Format | Description |
|---|---|---|---|
content |
Array |
FIDocument | The result collection. |
page |
string |
PageMetadata | Pagination details. |
links |
Array |
Link | Pagination links. |
FIDocument
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | The unique identifier for the document. |
docType |
string |
- | Transaction type. Supported values are: expense, invoice, cashadvance, payroll, obligation. |
companyId |
string |
- | Unique identifier for the company in SAP Concur. Maximum 32 chars. |
entityId |
string |
- | Unique identifier for the entity in SAP Concur. Maximum 32 chars. |
companyUuid |
string |
UUID |
UUID for the company in SAP Concur. Maximum 36 chars. |
erpSystemId |
string |
- | The external System ID that processed the document. Maximum 50 chars. |
document |
Array |
- | The JSON financial document. Review the FI sample documents below. |
docStatus |
string |
- | The financial document status. Supported values are: READY, ACKNOWLEDGED, POSTING_CONFIRMED_SUCCESS, POSTING_CONFIRMED_FAILURE. |
PageMetadata
| Name | Type | Format | Description |
|---|---|---|---|
size |
int32 | - | Total number of pages returned. |
totalElements |
int32 | - | Total count of records returned. |
totalPages |
int32 | - | Total number of pages returned. |
number |
int32 | - | Page location for which the result is returned, for example: first page starts with 0, second page starts with 1. |
Link
| Name | Type | Format | Description |
|---|---|---|---|
rel |
string |
- | Relation of link, for example: first, self, next, last. |
href |
string |
- | Complete URL for the paginated link. |
hreflang |
string |
- | Link language, if any. |
media |
string |
- | Media type, if any. |
title |
string |
- | Link title, if any. |
type |
string |
- | Link type, if any. |
deprecation |
string |
- | Deprecated indication, if any. |
AcknowledgeRequest
| Name | Type | Format | Description |
|---|---|---|---|
ids |
Array |
string |
The unique identifiers list for the financial documents. |
systemId |
string |
- | The external System ID that acknowledged the documents. |
AcknowledgeResponse
| Name | Type | Format | Description |
|---|---|---|---|
AcknowledgeResponse |
array |
AcknowledgeResponseItem | The JSON response. |
AcknowledgeResponseItem
| Name | Type | Format | Description |
|---|---|---|---|
acknowledgeResult |
string |
- | Acknowledge processing result. Supported values are: SUCCESS or FAILURE. |
code |
Int32 |
Service Codes | The Financial Integration Service Code. This is a particular code based on the success and failure of individual records for Acknowledging documents. |
docId |
string |
- | The financial document unique identifier. Maximum 32 chars. |
errorMessage |
string |
- | The error message, if any. |
systemId |
string |
- | The external system ID that acknowledged the documents. Maximum 50 chars. |
Confirmation Request
| Name | Type | Format | Description |
|---|---|---|---|
systemId |
string |
- | Required The external system ID that acknowledged the documents, it can be an empty string. Maximum 50 chars. |
postingConfirmations |
Array |
Posting Confirmation request item | Posting confirmations JSON request. |
Posting Confirmation Request Item
| Name | Type | Format | Description |
|---|---|---|---|
docId |
string |
- | The financial document ID to confirm. Maximum 32 chars. |
overallPostingStatusCode |
string |
- | Posting status. VALUES: error or success. |
postingDocs |
array |
Posting Documents Details | Posting documents details, if any. |
systemMessages |
array |
System Messages | Messages to post to SAP Concur, if any. |
Posting Documents Details
| Name | Type | Format | Description |
|---|---|---|---|
companyId |
string |
- | Required External system organizational unit ID. Maximum 32 chars. |
documentNumber |
string |
- | External system document identifier. Maximum 80 chars. |
fiscalYear |
int32 |
- | External system fiscal year. |
paymentRelevantLineItems |
array |
- | Payment relevant line items. This array is usually empty. |
postingDate |
string |
YYYY-MM-DD | External system posting date. |
System Messages
| Name | Type | Format | Description |
|---|---|---|---|
concurTransactionLineItemId |
string |
- | Report relevant line item id. |
messageId |
string |
- | External System message identifier. |
messageLanguage |
string |
- | Message Language code, example EN, FR. |
messageLongText |
array |
- | Message text, will be posted on the audit trail in SAP Concur. |
messageShortText |
string |
- | Message text, will be posted on the audit trail in SAP Concur. |
Posting Confirmation Response
| Name | Type | Format | Description |
|---|---|---|---|
PostingConfirmationResponse |
array |
Posting Confirmation Response Item | The JSON response body. |
PostingConfirmationResponseItem
| Name | Type | Format | Description |
|---|---|---|---|
postingConfirmationResult |
string |
- | Posting confirmation result. Supported values are: SUCCESS, SYSTEM_ERROR_OCCURRED, NOT_YET_ACKNOWLEDGED, DOCUMENT_NOT_FOUND, FAILURE, WAS_RECALLED. |
detailMessage |
string |
- | Posting confirmation message. |
code |
Int32 |
- | The Financial Service return code. |
docId |
string |
- | The document ID. Maximum 32 chars. |
errorMessage |
string |
- | The error message, if any. |
systemId |
string |
- | The external system ID that acknowledged the document. Maximum 50 chars. |
Payment Confirmation Request
| Name | Type | Format | Description |
|---|---|---|---|
systemId |
string |
- | Required The external system ID that acknowledged the documents, it can be an empty string. Maximum 50 chars. |
processingConfirmation |
Array |
Payment Confirmation Request Item | Payment confirmations JSON request. |
Payment Confirmation Request Item
| Name | Type | Format | Description |
|---|---|---|---|
docId |
string |
- | The financial document ID to confirm. Maximum 32 chars. |
processingStatusCode |
string |
- | Payment status. VALUES: CP, PP, RE, OB (Completely Paid, Partially paid, Reversal, Obsolete). Maximum 3 chars. |
additionalMessage |
string |
- | Reversal message or obsolete message if any. |
clearingDetails |
array |
Payment Documents Details | Payment documents details, if any. |
Payment Documents Details
| Name | Type | Format | Description |
|---|---|---|---|
clearingDate |
string |
- | Date the payment cleared. |
clearingAmount |
double |
- | Amount cleared. |
clearingCurrency |
string |
- | Currency value. |
receiver |
array |
Receiver Details | Receiver details. |
clearingReference |
array |
Clearing Reference Details | Clearing reference details. |
Receiver Details
| Name | Type | Format | Description |
|---|---|---|---|
receiverId |
string |
- | Receiver id |
receiverName |
double |
- | Name of receiver |
receiverType |
string |
- | Type of receiver |
Clearing Reference Details
| Name | Type | Format | Description |
|---|---|---|---|
companyCode |
string |
- | Company code. |
financialDocumentId |
string |
- | Document ID in ERP. |
fiscalYear |
string |
- | Fiscal year. |
paymentRef |
string |
- | Payment reference ID. |
paymentMethod |
string |
- | Payment method Where E=Electronic Fund Transfer or C = Check. |
Payment Confirmation Response
| Name | Type | Format | Description |
|---|---|---|---|
PaymentConfirmationResponse |
array |
Payment Confirmation Response Item | The JSON response body |
PaymentConfirmationResponseItem
| Name | Type | Format | Description |
|---|---|---|---|
paymentConfirmationResult |
string |
- | Payment confirmation result. Supported values are: SUCCESS, SYSTEM_ERROR_OCCURRED, NOT_POSTING_CONFIRMED, DOCUMENT_NOT_FOUND, FAILURE, NOOP. |
paymentRef |
string |
- | Any message corresponding to payment reference being processed. |
detailMessage |
string |
- | Payment confirmation message. |
code |
Int32 |
- | The financial service return code. |
docId |
string |
- | The document ID. Maximum 32 chars. |
errorMessage |
string |
- | The error message, if any. |
systemId |
string |
- | The external system ID that acknowledged the document. Maximum 50 chars. |
Example Financial Documents
Expense
{
"employee": {
"employeeFirstName": "FirstName",
"employeeLastName": "LastName",
"employeeId": "12345AB",
"employeeMI": null,
"employeeOrgUnit4Value": null,
"employeeOrgUnit5Value": null,
"employeeOrgUnit6Value": null,
"employeeCustom1Code": null,
"employeeCustom2Code": null,
"employeeCustom3Code": null,
"employeeCustom4Code": "001",
"employeeCustom5Code": "USPUG",
"employeeCustom6Code": "1234",
"employeeCustom7Code": null,
"employeeCustom8Code": null,
"employeeCustom9Code": null,
"employeeCustom10Code": null,
"employeeCustom11Code": null,
"employeeCustom12Code": null,
"employeeCustom13Code": null,
"employeeCustom14Code": null,
"employeeCustom15Code": null,
"employeeCustom16Code": "N",
"employeeCustom17Code": null,
"employeeCustom18Code": null,
"employeeCustom19Code": null,
"employeeCustom20Code": null,
"employeeCustom21Code": "US Group",
"employeeCustom1Value": null,
"employeeCustom2Value": null,
"employeeCustom3Value": null,
"employeeCustom4Value": "US Inc.",
"employeeCustom5Value": "US Publishing",
"employeeCustom6Value": "Operations",
"employeeCustom7Value": null,
"employeeCustom8Value": null,
"employeeCustom9Value": null,
"employeeCustom10Value": null,
"employeeCustom11Value": null,
"employeeCustom12Value": null,
"employeeCustom13Value": null,
"employeeCustom14Value": null,
"employeeCustom15Value": null,
"employeeCustom16Value": null,
"employeeCustom17Value": null,
"employeeCustom18Value": null,
"employeeCustom19Value": null,
"employeeCustom20Value": null,
"employeeCustom21Value": "US Group",
"employeeOrgUnit1Code": null,
"employeeOrgUnit2Code": null,
"employeeOrgUnit3Code": null,
"employeeOrgUnit4Code": null,
"employeeOrgUnit5Code": null,
"employeeOrgUnit6Code": null,
"employeeOrgUnit1Value": null,
"employeeOrgUnit2Value": null,
"employeeOrgUnit3Value": null
},
"report": {
"reportKey": 345,
"ledgerCode": "DEFAULT",
"reportId": "D0719B539ED64FE612AB",
"totalApprovedAmount": 200,
"reportName": "Trip to Minneapolis",
"isTest": "N",
"reportStartDate": null,
"reportEndDate": null,
"employeeCurrencyAlphaCode": "USD",
"payrollPayIndicator": "N",
"payrollPaymentClearingAccountCode": null,
"cashAdvanceReturnsAmount": 0E-8,
"revisionNumber": "1",
"versionId": "4",
"homeCountryCode": "US",
"reportCustom20Code": null,
"reportCustom1Value": null,
"reportCustom2Value": null,
"reportCustom3Value": null,
"reportCustom4Value": null,
"reportCustom5Value": null,
"reportCustom6Value": null,
"reportCustom7Value": null,
"reportCustom8Value": null,
"reportCustom9Value": null,
"reportCustom10Value": null,
"reportCustom11Value": null,
"reportCustom12Value": null,
"reportCustom13Value": null,
"reportCustom14Value": null,
"reportCustom15Value": "US Group",
"reportCustom16Value": null,
"reportCustom17Value": null,
"reportCustom18Value": null,
"reportCustom19Value": null,
"reportCustom20Value": null,
"reportOrgUnit1Code": null,
"reportOrgUnit2Code": null,
"reportOrgUnit3Code": null,
"reportOrgUnit4Code": null,
"reportOrgUnit5Code": null,
"reportOrgUnit6Code": null,
"reportOrgUnit1Value": null,
"reportOrgUnit2Value": null,
"reportCustom5Code": null,
"reportCustom6Code": null,
"reportCustom7Code": null,
"reportCustom8Code": null,
"reportCustom9Code": null,
"reportCustom10Code": null,
"reportCustom11Code": null,
"reportCustom12Code": null,
"reportCustom13Code": null,
"reportCustom14Code": null,
"reportCustom15Code": "US Group",
"reportCustom16Code": "12345AB",
"reportCustom17Code": null,
"reportCustom18Code": null,
"reportCustom19Code": null,
"reportSubmitDate": "2018-03-02T18:12:03.050Z",
"reportUserDefinedDate": "2018-03-02T00:00:00.000Z",
"reportPaymentProcessingDate": "2018-03-02T18:34:30.260Z",
"reportCreationDate": "2018-03-02T18:08:37.887Z",
"reportCustom1Code": "12345AB",
"reportCustom2Code": null,
"reportCustom3Code": null,
"reportCustom4Code": null,
"reportOrgUnit3Value": null,
"reportOrgUnit4Value": null,
"reportOrgUnit5Value": null,
"reportOrgUnit6Value": null
},
"expenseEntry": [
{
"cardProgramTypeCode": null,
"entryCustom20Code": null,
"entryCustom21Code": null,
"entryCustom22Code": null,
"entryCustom23Code": null,
"entryCustom24Code": null,
"entryCustom25Code": null,
"entryCustom26Code": null,
"entryCustom27Code": null,
"entryCustom28Code": null,
"entryCustom29Code": null,
"entryCustom30Code": null,
"entryCustom31Code": null,
"entryCustom32Code": null,
"entryCustom33Code": null,
"entryCustom34Code": null,
"entryCustom35Code": "US",
"entryCustom36Code": null,
"entryCustom37Code": null,
"entryCustom38Code": null,
"entryCustom39Code": "0.00000000",
"entryCustom40Code": "200.00000000",
"reportEntryTransactionAmount": 200,
"entryLocationCityName": "Minneapolis",
"entryCountrySubCode": "US-MN",
"entryIsBillable": "N",
"entryOrgUnit1Code": null,
"entryOrgUnit2Code": null,
"entryOrgUnit3Code": null,
"entryOrgUnit4Code": null,
"entryOrgUnit5Code": null,
"entryOrgUnit6Code": null,
"offsetPayType": "N",
"entryCountryCode": "US",
"entryUuid": null,
"entrySupplierTaxID": null,
"entryCustom1Code": null,
"entryCustom2Code": null,
"entryCustom3Code": null,
"entryCustom4Code": null,
"entryCustom5Code": null,
"entryCustom6Code": null,
"entryCustom7Code": null,
"entryCustom8Code": null,
"entryCustom9Code": null,
"entryCustom10Code": null,
"entryCustom11Code": null,
"entryCustom12Code": null,
"entryCustom13Code": null,
"entryCustom14Code": null,
"entryCustom15Code": null,
"entryCustom16Code": null,
"entryCustom17Code": null,
"entryCustom18Code": null,
"entryCustom19Code": null,
"cardAccountID": null,
"cardTransactionID": null,
"cardTransactionAmount": null,
"cardTransactionCurrency": null,
"cardTransactionPostedAmount": null,
"cardTransactionPostedCurrency": null,
"clearingAccountCode": null,
"entryApprovedAmount": 200,
"expensePayIndicator": "N",
"entryId": "A92F3AD820F4E546800515258C3E0893",
"entryDescription": "",
"entryVendorCode": "Astron Hotels",
"entryCustom1Value": null,
"entryCustom2Value": null,
"entryCustom3Value": null,
"entryCustom4Value": null,
"entryCustom5Value": null,
"entryCustom6Value": null,
"entryCustom7Value": null,
"entryCustom8Value": null,
"entryCustom9Value": null,
"entryCustom10Value": null,
"entryCustom11Value": null,
"entryCustom12Value": null,
"entryCustom13Value": null,
"entryCustom14Value": null,
"entryCustom15Value": null,
"entryCustom16Value": null,
"entryCustom17Value": null,
"entryCustom18Value": null,
"entryCustom19Value": null,
"entryCustom20Value": null,
"entryCustom21Value": null,
"entryCustom22Value": null,
"entryCustom23Value": null,
"entryCustom24Value": null,
"entryCustom25Value": null,
"entryCustom26Value": null,
"entryCustom27Value": null,
"entryCustom28Value": null,
"entryCustom29Value": null,
"entryCustom30Value": null,
"entryCustom31Value": null,
"entryCustom32Value": null,
"entryCustom33Value": null,
"entryCustom34Value": null,
"entryCustom35Value": null,
"entryCustom36Value": null,
"entryCustom37Value": null,
"entryCustom38Value": null,
"entryCustom39Value": null,
"entryCustom40Value": null,
"entryOrgUnit1Value": null,
"entryOrgUnit2Value": null,
"entryOrgUnit3Value": null,
"entryOrgUnit4Value": null,
"entryOrgUnit5Value": null,
"entryOrgUnit6Value": null,
"entryLocationName": "Minneapolis",
"entryReceiptId": "E921EECCBCBA393EAC5A9212DCE57D9B",
"entryElectronicReceiptId": null,
"allocation": [
{
"allocationId": "76A1774FEC7D0C4981FBB332AB5671A3",
"allocationCustom1Code": "",
"allocationCustom2Code": "",
"allocationCustom3Code": "",
"allocationCustom4Code": null,
"allocationCustom5Code": null,
"allocationCustom6Code": null,
"allocationCustom7Code": null,
"allocationCustom8Code": null,
"allocationCustom9Code": null,
"allocationCustom10Code": null,
"allocationCustom11Code": null,
"allocationCustom12Code": null,
"allocationCustom13Code": null,
"allocationCustom14Code": null,
"allocationCustom15Code": null,
"allocationCustom16Code": null,
"allocationCustom17Code": null,
"allocationCustom18Code": null,
"allocationCustom19Code": null,
"allocationCustom20Code": null,
"allocationCustom1Value": null,
"allocationCustom2Value": null,
"allocationCustom3Value": null,
"allocationCustom4Value": null,
"allocationCustom5Value": null,
"allocationCustom6Value": null,
"allocationCustom7Value": null,
"allocationCustom8Value": null,
"allocationCustom9Value": null,
"allocationCustom10Value": null,
"allocationCustom11Value": null,
"allocationCustom12Value": null,
"allocationCustom13Value": null,
"allocationCustom14Value": null,
"allocationCustom15Value": null,
"allocationCustom16Value": null,
"allocationCustom17Value": null,
"allocationCustom18Value": null,
"allocationCustom19Value": null,
"allocationCustom20Value": null,
"allocationPercentage": 100,
"journal": [
{
"amountGrossCard": null,
"journalAccountCode": "125ABC",
"journalPayee": "EMPL",
"journalPayer": "COMP",
"cardTransactionReferenceNumber": null,
"amountNetOfReclaim": 150,
"amountNetOfTax": 150,
"amountGross": 150,
"taxGuid": [],
"accountingTransactionType": null
},
{
"amountGrossCard": null,
"journalAccountCode": "12345",
"journalPayee": "EMPL",
"journalPayer": "COMP",
"cardTransactionReferenceNumber": null,
"amountNetOfReclaim": 50,
"amountNetOfTax": 50,
"amountGross": 50,
"taxGuid": [],
"accountingTransactionType": null
}
],
"tax": []
}
],
"entryReceiptType": "N",
"entryExchangeRateDirection": "M",
"entryIsPersonal": "N",
"entryVendorDescription": "Astron Hotels",
"legacyEntryId": 294,
"liabilityAccountCode": null,
"expenseTypeName": "Hotel",
"entryDate": "2018-02-17T00:00:00.000Z",
"entryCurrAlphaCode": "USD",
"entryExchangeRate": 1,
"expenseTypeCode": "LODNG",
"cardStatementPeriodStartDate": null,
"cardStatementPeriodEndDate": null,
"reportEntryPatKey": "CASH"
}
],
"cashAdvanceApplication": [
{
"cashAdvanceClearingAccountCode": "12345",
"cashAdvanceId": "6A107A548D1B4B49BBF370DF02EC890D",
"cashAdvanceApplicationAmount": -50,
"cashAdvanceTransactionType": 2
}
]
}
Example - Invoice
{
"requestHeader":{
"ledgerCode":"DEFAULT",
"clearingAccountCode":null,
"invoiceDate":"08/08/2018",
"reqKey":35,
"postingDate":null,
"poNumber":null,
"isTest":"N",
"deliverySlipNumber":null,
"discountPercentage":null,
"paymentDueDate":"09/07/2018",
"requestId":"9B1D30723CBF4F86A574",
"requestOrgUnit4Code":null,
"requestOrgUnit5Code":null,
"requestOrgUnit6Code":null,
"currencyAlphaCode":"USD",
"ledgerName":"DEFAULT",
"vendorInvoiceNumber":"25688",
"multiplePurchaseOrder":"N",
"invoicePayIndicator":"N",
"payMethodType":"CLIENT",
"submitDate":"2018-09-05T03:37:42.923Z",
"requestTotal":50.00000000,
"revisionNumber":"1",
"processCompleteDate":null,
"invoiceReceivedDate":null,
"requestOrgUnit1Value":null,
"requestOrgUnit2Value":null,
"requestOrgUnit3Value":null,
"requestOrgUnit4Value":null,
"requestOrgUnit5Value":null,
"requestOrgUnit6Value":null,
"versionId":"4",
"requestOrgUnit1Code":null,
"requestOrgUnit2Code":null,
"requestOrgUnit3Code":null,
"requestCustom21Code":null,
"requestCustom22Code":null,
"requestCustom1Value":null,
"requestCustom2Value":null,
"requestCustom3Value":null,
"requestCustom4Value":null,
"requestCustom5Value":null,
"requestCustom6Value":null,
"requestCustom7Value":null,
"requestCustom8Value":null,
"requestCustom9Value":null,
"requestCustom10Value":"Default-Change to Client",
"requestCustom11Value":null,
"requestCustom12Value":null,
"requestCustom13Value":null,
"requestCustom14Value":null,
"requestCustom15Value":null,
"requestCustom16Value":null,
"requestCustom17Value":null,
"requestCustom18Value":null,
"requestCustom19Value":null,
"requestCustom20Value":null,
"requestCustom21Value":null,
"requestCustom22Value":null,
"requestCustom23Value":null,
"requestCustom24Value":null,
"amountNetInvoice":50.00000000,
"amountShippingTotal":0E-8,
"requestTitle":"FIS Test",
"discountTermsDays":null,
"requestCustom1Code":null,
"requestCustom2Code":null,
"requestCustom3Code":null,
"requestCustom4Code":null,
"requestCustom5Code":null,
"requestCustom6Code":null,
"requestCustom7Code":null,
"requestCustom8Code":null,
"requestCustom9Code":null,
"requestCustom10Code":"Default",
"requestCustom11Code":null,
"requestCustom12Code":null,
"requestCustom13Code":null,
"requestCustom14Code":null,
"requestCustom15Code":null,
"requestCustom16Code":null,
"requestCustom17Code":null,
"requestCustom18Code":null,
"requestCustom19Code":null,
"requestCustom20Code":null,
"requestCustom24Code":null,
"netPaymentTermDays":"30",
"requestCreationDate":"2018-09-05T03:37:00.143Z",
"requestCustom23Code":null,
"requestDescription":null
},
"ownerEmployee":{
"employeeCustom20Value":null,
"employeeCustom21Value":"System",
"employeeCustom10Code":"Default",
"employeeOrgUnit1Code":null,
"employeeOrgUnit2Code":null,
"employeeOrgUnit3Code":null,
"employeeOrgUnit4Code":null,
"employeeOrgUnit5Code":null,
"employeeOrgUnit6Code":null,
"employeeOrgUnit1Value":null,
"employeeOrgUnit2Value":null,
"employeeOrgUnit3Value":null,
"employeeOrgUnit4Value":null,
"employeeOrgUnit5Value":null,
"employeeOrgUnit6Value":null,
"employeeCustom1Code":"ext-record-4",
"employeeCustom2Code":null,
"employeeCustom3Code":null,
"employeeCustom4Code":null,
"employeeCustom5Code":null,
"employeeCustom6Code":null,
"employeeCustom7Code":null,
"employeeCustom8Code":null,
"employeeCustom9Code":"28",
"employeeCustom11Code":null,
"employeeCustom13Code":null,
"employeeCustom14Code":null,
"employeeCustom15Code":null,
"employeeCustom16Code":"N",
"employeeCustom17Code":null,
"employeeCustom18Code":null,
"employeeCustom19Code":null,
"employeeCustom20Code":null,
"employeeCustom21Code":"SYS",
"employeeCustom1Value":null,
"employeeCustom2Value":null,
"employeeCustom3Value":null,
"employeeCustom4Value":null,
"employeeCustom5Value":null,
"employeeCustom6Value":null,
"employeeCustom7Value":null,
"employeeCustom8Value":null,
"employeeCustom9Value":"522 Product",
"employeeCustom10Value":"Default-Change to Client",
"employeeCustom11Value":null,
"employeeCustom12Value":null,
"employeeCustom13Value":null,
"employeeCustom14Value":null,
"employeeCustom15Value":null,
"employeeCustom16Value":null,
"employeeCustom17Value":null,
"employeeCustom18Value":null,
"employeeCustom19Value":null,
"employeeId":"12345AB",
"employeeMI":"C",
"employeeFirstName":"FirstName",
"employeeLastName":"LastName",
"employeeCustom12Code":null
},
"vendor":{
"vendorName":"Test Vendor",
"vendorCode":"94F538F2C3224C6E871CFED9F0F8333A",
"vendorShipFromAddressCode":null,
"vendorRemitToAddressCode":"333",
"vendorContactFirstName":null,
"vendorContactLastName":null
},
"lineItem":[
{
"allocation":[
{
"journal":{
"accountCode":"MATER",
"amountShipping":0,
"amountNet":50.00,
"amountGross":50.00,
"tax":null
},
"allocationAccountCode":"MATER",
"allocationCustom6Code":null,
"allocationCustom7Code":null,
"allocationCustom8Code":null,
"allocationCustom9Code":null,
"allocationCustom10Code":null,
"allocationCustom11Code":null,
"allocationCustom12Code":null,
"allocationCustom13Code":null,
"allocationCustom14Code":null,
"allocationCustom15Code":null,
"allocationCustom16Code":null,
"allocationCustom17Code":null,
"allocationCustom18Code":null,
"allocationCustom19Code":null,
"allocationCustom20Code":null,
"allocationCustom1Code":"",
"allocationCustom2Code":"",
"allocationCustom3Code":"",
"allocationCustom4Code":null,
"allocationCustom5Code":null,
"allocationPercentage":100.00000000,
"allocationCustom1Value":null,
"allocationCustom2Value":null,
"allocationCustom3Value":null,
"allocationCustom4Value":null,
"allocationCustom5Value":null,
"allocationCustom6Value":null,
"allocationCustom7Value":null,
"allocationCustom8Value":null,
"allocationCustom9Value":null,
"allocationCustom10Value":null,
"allocationCustom11Value":null,
"allocationCustom12Value":null,
"allocationCustom13Value":null,
"allocationCustom14Value":null,
"allocationCustom15Value":null,
"allocationCustom16Value":null,
"allocationCustom17Value":null,
"allocationCustom18Value":null,
"allocationCustom19Value":null,
"allocationCustom20Value":null,
"allocationKey":158
}
],
"receiptNumbers":[
],
"expenseTypeName":"Material",
"poLineNumber":null,
"externalLineItemId":null,
"expenseTypeCode":"2000 ",
"lineItemPurchaseOrderNumber":null,
"lineItemCode":null,
"lineItemDeliverySlipNumber":null,
"lineItemUnitPrice":50.00000000,
"lineItemSequenceOrder":1,
"lineItemQuantity":1.00000000,
"lineItemCustom1Value":null,
"lineItemCustom2Value":null,
"lineItemCustom3Value":null,
"lineItemCustom4Value":null,
"lineItemCustom5Value":null,
"lineItemCustom6Value":null,
"lineItemCustom7Value":null,
"lineItemCustom8Value":null,
"lineItemCustom9Value":null,
"lineItemCustom10Value":null,
"lineItemCustom11Value":null,
"lineItemCustom12Value":null,
"lineItemCustom13Value":null,
"lineItemCustom14Value":null,
"lineItemCustom15Value":null,
"lineItemCustom16Value":null,
"lineItemCustom17Value":null,
"lineItemCustom18Value":null,
"lineItemCustom19Value":null,
"lineItemCustom20Value":null,
"lineItemCustom1Code":null,
"lineItemCustom2Code":null,
"lineItemCustom3Code":null,
"lineItemCustom4Code":null,
"lineItemCustom5Code":null,
"lineItemCustom6Code":null,
"lineItemCustom7Code":null,
"lineItemCustom8Code":null,
"lineItemCustom9Code":null,
"lineItemCustom10Code":null,
"lineItemCustom11Code":null,
"lineItemCustom12Code":null,
"lineItemCustom13Code":null,
"lineItemCustom14Code":null,
"lineItemCustom15Code":null,
"lineItemCustom16Code":null,
"lineItemCustom17Code":null,
"lineItemCustom18Code":null,
"lineItemCustom19Code":null,
"lineItemCustom20Code":null,
"lineItemDescription":"Merchandise"
}
]
}
Example - Cash Advance
{
"employeeData": {
"employeeFirstName": "FirstName",
"employeeLastName": "LastName",
"employeeId": "12345ID",
"employeeMI": null,
"employeeOrgUnit5Code": null,
"employeeOrgUnit6Code": null,
"employeeOrgUnit1Value": null,
"employeeOrgUnit2Value": null,
"employeeOrgUnit3Value": null,
"employeeOrgUnit4Value": null,
"employeeOrgUnit5Value": null,
"employeeOrgUnit6Value": null,
"employeeCustom1Code": null,
"employeeCustom2Code": null,
"employeeCustom3Code": null,
"employeeCustom4Code": "001",
"employeeCustom5Code": "ABUFG",
"employeeCustom6Code": "2567",
"employeeCustom7Code": null,
"employeeCustom8Code": null,
"employeeCustom9Code": null,
"employeeCustom10Code": null,
"employeeCustom11Code": null,
"employeeCustom13Value": null,
"employeeCustom14Value": null,
"employeeCustom15Value": null,
"employeeCustom16Value": null,
"employeeCustom17Value": null,
"employeeCustom18Value": null,
"employeeCustom19Value": null,
"employeeCustom20Value": null,
"employeeCustom21Value": "US Group",
"employeeCustom12Code": null,
"employeeCustom13Code": null,
"employeeCustom14Code": null,
"employeeCustom15Code": null,
"employeeCustom16Code": "N",
"employeeCustom17Code": null,
"employeeCustom18Code": null,
"employeeCustom19Code": null,
"employeeCustom20Code": null,
"employeeCustom21Code": "US Group",
"employeeCustom1Value": null,
"employeeCustom2Value": null,
"employeeCustom3Value": null,
"employeeCustom4Value": "US Inc.",
"employeeCustom5Value": "US Publishing",
"employeeCustom6Value": "Operations",
"employeeCustom7Value": null,
"employeeCustom8Value": null,
"employeeCustom9Value": null,
"employeeCustom10Value": null,
"employeeCustom11Value": null,
"employeeCustom12Value": null,
"employeeOrgUnit1Code": null,
"employeeOrgUnit2Code": null,
"employeeOrgUnit3Code": null,
"employeeOrgUnit4Code": null
},
"cashAdvanceData": {
"locationName": null,
"exchangeRate": 1,
"countryCode": null,
"currencyAlphaCode": "USD",
"cashAdvanceId": "FE884EE31617CF4CABE36C7FC44512A1",
"clearingAccountCode": null,
"purpose": null,
"paymentMethod": 0,
"requestAmount": 150,
"requestDate": "2018-03-03T02:16:51.363Z",
"issuedDate": "2018-03-06T03:54:36.993Z",
"isTest": "N",
"countrySubCode": null,
"requestedDisbursementDate": null,
"travelStartDate": null,
"travelEndDate": null,
"currencyNumCode": "840",
"expensePayIndicator": "N",
"employeeCurrencyAlphaCode": "USD",
"cardAccountID": null,
"cardTransactionID": null,
"cardTransactionAmount": null,
"cardTransactionCurrency": null,
"cardTransactionPostedAmount": null,
"cardTransactionPostedCurrency": null,
"transactionType": 1,
"name": "Cash Advance Testing 3"
},
"journalData": [
{
"accountCode": "12345",
"amount": 150,
"payee": "EMPL",
"debitOrCredit": "DR",
"payer": "COMP",
"paymentCode": "Cash"
}
]
}
Use Cases-Financial Integration
- Expense Posting Without Tax
- Simple Out-of-Pocket Cash Expense
- VAT Handling
- Non-Deductible VAT
- Itemization
- Cost Allocation
- Cash Advances
- Credit Card Types
- Employee Paid Credit Card
- Payment via Employee Vendor Account
- Payment via Credit Card Vendor Account (Split Payment)
- Credit Transaction via Credit Card Vendor Account (Split Payment)
- Simple IBCP Corporate Card Charge With Itemization
- IBCP With Personal Expense: No Out-of-Pocket
- IBCP (With Offsets) With Personal Expense: Out-of-Pocket Greater Than Personal Expense
- IBCP (With Offsets) With Personal Expense: Out-of-Pocket Less Than Personal Expense
- Company Paid Credit Card
- CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Consolidated or Verbose Extract)
- CBCP Corporate Card Charge with Itemization and Personal Expense (Net Due Employee With Consolidation)
- CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Verbose Extract)
- CBCP Corporate Card Charge With Itemization and Personal Expense (Net Due Employee Without Offsets)
Overview
The use case examples below illustrate expense scenarios and the related posting records. Posting records will vary based on app design. The use case documentation is not meant to be a comprehensive list of all use cases and expense scenarios. However, the JSON from the Financial Integration Service will provide all the required data to support the all potential financial use cases.
Simple Expense Posting Without Tax
Simple Out-of-Pocket Cash Expense
Description
Very simple expense report with only a few expense items without VAT, for example, US expense report.
Posting Example
Expense Report with one expense item: Taxi – USD 10
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Expense (Taxi) | USD 10 | - |
| Employee Vendor | - | USD 10 |
Standard Accounting Extract Details
Simple Out-of-Pocket Cash Credit
Description
The user receives a USD 50 cash rebate for a hotel stay that was fully reimbursed on a previous expense report. Being a good corporate citizen the user enters a single USD 50 cash credit transaction and assigns it to the Expense Type "Hotel." The expense is a legitimate business expense, not a personal expense. It is not itemized.
Posting Example
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Expense (Hotel) | - | USD 50 |
| Employee Vendor | USD 50 | - |
Standard Accounting Extract Details
Simple Personal Car Mileage Expense
Description
The user enters a single personal car mileage transaction for a round trip to the airport of 60 miles. The expense is a legitimate business expense, not a personal expense. It is not itemized.
Posting Example
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Expense (Mileage) | USD 24.30 | - |
| Employee Vendor | - | USD 24.30 |
Standard Accounting Extract Details
Travel Allowances – Company Specific Rate Greater Than Government Rate
Description
A German traveler receives meal per diems that are higher the legal rates. In this case he gets EUR 50 instead of the EUR 24 legal amount allowed for a full day. As a result the amount reimbursed to the employee over the legal daily rate is taxable to the employee.
Posting Example
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Expense (Meals) | EUR 50 | - |
| Employee Vendor (non-taxable) | - | EUR 24 |
| Employee Vendor (taxable) | - | EUR 26 |
Standard Accounting Extract Details
VAT Handling
The SAP Concur system, when configured and applicable, will calculate the related VAT tax for a given transaction. This determination relies on the customer’s tax configuration and will vary by customer and country. The posting document will include all related VAT amounts that are calculated.
How the VAT is handled is determined based on the Tax Code customization in ERP and the related VAT use cases that the partner application supports.
Expense Posting With Single Tax Item
Description
Very simple expense report with only a few expense items with VAT, for example, German expense report.
Posting Example
The posting below is one example of how the expense gets recorded by the customer based on their ERP set up and requirements.
Expense Report with one expense item: Laundry – EUR 10 (including 16 % - EUR 1.60 VAT).
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Expense (amount net of tax) | EUR 8.40 | - |
| VAT | EUR 1.60 | - |
| Employee Vendor (gross amount) | - | EUR 10 |
Non-Deductible VAT
The SAP Concur system, when configured and applicable, will calculate the related VAT tax for a given transaction. In some cases, this tax is deductible if it meets certain country-based requirements. In other cases, it is not deductible. This determination relies on the customer’s tax configuration and will vary by customer and country. The posting document will include all related VAT amounts that are calculated.
How the VAT is handled is determined based on the Tax Code customizing in ERP and the related VAT use cases that the partner application supports.
Description
Very simple expense report with only a few expense items with VAT, for example, German expense report.
Posting Example
The posting below is one example of how the expense gets recorded by the customer based on their ERP set up and requirements.
Expense Report with one expense item: Gas – EUR 100 (including 15.97% - EUR 15.97 VAT)
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Expense (amount net of tax) | EUR 84.03 | - |
| Non-deductible VAT Expense | EUR 15.97 | - |
| Employee Vendor (gross amount) | - | EUR 100 |
Expense Posting With Multiple Tax Items
Description
For a country like Canada, with multiple tax jurisdictions the entry may have multiple tax lines representing calculated VAT for each jurisdiction. The posting document will include all related tax lines and corresponding tax amounts.
Posting Example
The posting below is one example of how the expense gets recorded by the customer based on their ERP set up and requirements.
Expense Report with one expense item: Local Phone – CAD 100 with multiple tax jurisdictions (for example, tax type 1, tax type 2).
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Expense (amount net of tax) | 88.50 CAD | - |
| Tax Type 1 | CAD 4.42 | - |
| Tax Type 2 | CAD 7.08 | - |
| Employee Vendor (gross amount) | - | CAD 100 |
Partially Deductible VAT
Description
In some cases it could be possible that the whole VAT amount is not deductible. This case has similar posting options as non-deductible VAT.
Posting Example
The posting below is one example of how the expense gets recorded by the customer based on their ERP set up and requirements.
For a hotel receipt of CAD 55 (including 11.5% - CAD 6.32 VAT) the VAT is only deductible by 50%.
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Expense (amount net of tax) | CAD 48.68 | - |
| VAT | CAD 3.16 | - |
| Non-deductible VAT | CAD 3.16 | - |
| Employee Vendor (gross amount) | - | CAD 55 |
Foreign Expense Report Without VAT
Description
The SAP Concur system, when configured and applicable, will calculate the related VAT tax for a given transaction. In some cases, this tax is deductible if it meets certain country-based requirements. In other cases, it is not deductible. This determination relies on the customer’s tax configuration and will vary by customer and country. The posting document will include all related VAT amounts that are calculated.
In case an employee from a country with VAT enters a foreign receipt and the included VAT is not claimable, the document has to be posted with a 0% VAT tax code. In SAP Concur this tax code is normally customized for the tax authority in the non-domestic code field. Again, this will vary based on the exact use case and customer’s tax configuration.
Posting Example
A UK employee submits an entry for a US-based training. In this case the posting document will include U.S tax included on the receipt and the posting will be handled in the ERP according to the desired posting record. It’s common that the posting record will include the tax amount as part of the overall expense (in this case Hotel) but a valid tax code with a 0% rate will also be included. This allows the customer to report on foreign taxes paid but which are not reclaimable.
The posting below is one example of how the expense gets recorded by the customer based on their ERP set up and requirements.
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Room Rate | GBP 60.24 | - |
| Hotel Tax | GBP 20.08 | - |
| Card Vendor | - | GBP 80.32 |
Itemization
Itemized Expense Items
Description
John flew to New York to meet with a client and stayed one night at the Marriot. An original receipt is split into several parts, for example, lodging costs per night, room tax, and breakfast. All items should be processed separately in the Journal Section, SAE, and JSON.
Posting Example
For a hotel receipt of USD 325 where the costs per night and other expenses should be posted separately.
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Room Rate | USD 250 | - |
| Room Tax | USD 50 | - |
| Breakfast | 25 USD | - |
| Employee Vendor | - | USD 325 |
Standard Accounting Extract Details
Cost Allocation
What is cost allocation? Allocation is defined as a part of cross-charging is the ability to assign cost of an expense to multiple organizational units such as department, cost center, project code, etc.
When allocating the expense across multiple cost centers, the user needs to pick the correct code from the most granular level which may be from the Expense Entry, Journal Entry, and/or Allocation Entry depending on whether or not the customer is configured to use the allocation fields. Cost center codes should NEVER be picked up from the Employee Entry section because an employee may have to charge another department for a percentage of a transaction.
Expense With Multiple Cost Allocations
Description
Similar to the itemized expense example, however, the breakfast cost is allocated between two different cost centers.
Posting Example
For a hotel receipt of USD 325 where the costs per night and other expenses should be posted separately.
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Room Rate | USD 250 | - |
| Room Tax | USD 50 | - |
| Breakfast | 25 USD | - |
| Employee Vendor | - | USD 325 |
Extract Details
Standard Accounting Extract Details
NOTE: The room rate and room tax is charged to the same cost center as in the itemized expense example. Only the breakfast cost is allocated 50% between two different cost centers: 0021-Bellevue1 and Top Management. The allocation section is towards the bottom of the JSON.
Cash Advances
Issuance
Paid Cash
Description
An employee requests a cash advance to be paid in cash or via transfer.
Posting Example
Employee requests a cash advance of USD 7000 for trip to TechEd.
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Cash Advance Clearing Account | USD 7000 | - |
| Employee Vendor | - | USD 7000 |
Standard Accounting Extract Details
Note: This extract example is the same as Itemized Expense Items.
Application
Cash Advance Is Lower Than the Payout Amount
Description
The employee enters an expense report and assigns a cash advance. This cash advance reduces the employee’s payout amount. Only the difference between the sum of the expense items paid by the employee and the cash advance will be paid to the employee.
Posting Example
The user has requested and received an GBP 300 cash advance. In the course of travel the user incurs the following cash expenses: GBP 245 for a rental car, GBP 60 for a business meal, and GBP 10 for parking. After returning from travel the user finds the GBP 300 cash advance has been issued via the corporate card import process. He assigns the GBP 300 cash advance to an expense report and enters the three cash expenses and submits. The expenses are not itemized. The expenses are legitimate business expenses.
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Car Rental | GBP 245 | - |
| Meal | GBP 60 | - |
| Parking | GBP 10 | - |
| Cash Advance Clearing Account | GBP 300 | - |
| Employee Vendor | - | GBP 15 |
Extract Details
Cash Advance Is Higher Than the Payout Amount
Description
The employee enters an expense report and assigns a cash advance. If the cash advance is higher than the sum of the expense items paid by the employee the employee owes the difference to the company.
Posting Example
The user has requested and received a GBP 400 cash advance and during travel spends GBP245 on a rental car, GBP 60 on a business meal, and GBP 10 on parking. The user assigns the GBP 400 cash advance to the expense report and enters the three cash expenses and submits. The expenses are not itemized. The expenses are legitimate business expenses. Because the total of the cash advance exceeds the sum of the business expenses the net result of the expense report is that the employee owes the company the balance. The employee will write a check to the company for the balance (GBP 85) and enter a cash advance return transaction in that amount to net the expense report to zero.
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Car Rental | GBP 245 | - |
| Meals | GBP 60 | - |
| Parking | GBP 10 | - |
| Cash Advance Clearing Account | - | GBP 400 |
| Employee Vendor | GBP 85 | - |
Extract Details
Credit Card Types
- IBIP - Individual Bill – Individual payment paid by employee (employee liability).
- IBCP - Individual Bill – Company payment split payment (employee liability for personal use. Company liability for approved business expenses).
- CBCP - Company Bill – Company payment paid by company (company liability).
Employee Paid Credit Card
Payment via Employee Vendor Account
Description
Credit card items with employee liability should be paid to the employee’s bank account like cash paid expenses. (IBIP)
Posting Example
Expense Report with one employee paid credit card item: Taxi - USD 10.
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Expense (Taxi) | USD 10 | - |
| Employee Vendor | - | USD 10 |
Payment via Credit Card Vendor Account (Split Payment)
Description
Approved business expenses should be paid to the credit card instead of the employee’s bank account. (IBCP)
Posting Example
Car rental was paid with IBIP card for USD 56.10.
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Expense (Car Rental) | USD 56.10 | - |
| Credit Card Vendor | - | USD 56.10 |
Credit Transaction via Credit Card Vendor Account (Split Payment)
Example
The user receives a USD 349 credit on the corporate card for an unused airline ticket. The credit transaction is displayed as a pre-populated corporate card transaction and the user selects it and submits an expense report. The expense is a legitimate business expense, not a personal expense. It is not itemized.
Posting
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Expense (Airfare) | - | USD 349 |
| Credit Card Vendor | USD 349 | - |
Simple IBCP Corporate Card Charge With Itemization
Example
John flew to New York to meet with a client and stayed one night at the Marriot. An original receipt is split into several parts, for example, lodging costs per night, room tax, and breakfast. All items should be processed separately in the Journal Section, SAE, and JSON.
Posting Example
For a hotel receipt of USD 325 where the costs per night and other expenses should be posted separately.
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Room Rate | USD 250 | - |
| Room Tax | USD 50 | - |
| Breakfast | USD 25 | - |
| Employee Vendor | - | USD 325 |
IBCP With Personal Expense: No Out-of-Pocket
NOTE: Personal expenses paid by an IBCP credit card will not be included in the JSON.
Example
John flew to New York to meet with a client and stayed one night at the Marriot. An original receipt is split into several parts, for example, lodging costs per night, room tax, and breakfast. All items should be processed separately in the Journal Section, SAE, and JSON. Since breakfast is a personal expense, it will be included in the extract but NOT in the JSON.
Posting Example
For a hotel receipt of USD 325 where the costs per night and other expenses should be posted separately.
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Room Rate | USD 250 | - |
| Room Tax | USD 50 | - |
| Breakfast (personal) | USD 25 | - |
| Employee Vendor | - | USD 325 |
IBCP with Personal Expense Where Out-of-Pocket Exceeds the Personal Expense
NOTE: Personal expenses paid by an IBCP credit card will not be included in the JSON when a non-offsetting payment is used because it’s not relevant to the company’s accounting record.
Without Offsetting
Example
The user assigns a pre-populated corporate card transaction to the expense report. The transaction is a Hotel expense in the amount of USD 284. The hotel expense consists of a two-night stay at USD 125 per night and the user had a USD 20 dinner after checking in and ordered an in-room movie for USD 14 that the company does not reimburse for. The expense is itemized. The expense is a legitimate business expense with the exception of the in-room movie that the user marks as a non-reimbursable expense on the expense report. The expense report also includes an out-of-pocket cash transaction for a taxi at USD 35.
Posting
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Room Rate | USD 125 | - |
| Room Rate | USD 125 | - |
| Dinner | USD 20 | - |
| Taxi | USD 35 | - |
| Credit Card Vendor | - | USD 270 |
| Employee Vendor | - | USD 35 |
With Offsetting
When using offsets the amount due the employee for out-of-pocket expenses is netted (or offset) against the amount marked as personal, resulting in an entry reflecting either the final amount the employee owes the company (assumes personal exceeds out of pocket) or final amount company owes the employee (reduced by any personal amounts).
Posting
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Room Rate | USD 125 | - |
| Room Rate | USD 125 | - |
| Dinner | USD 20 | - |
| Taxi | USD 14 | - |
| Taxi | USD 21 | - |
| Credit Card Vendor | - | USD 284 |
| Employee Vendor | - | USD 21 |
Extract Details
IBCP With Personal Expense Where Out-of-Pocket Is Less Than Personal Expense
NOTE: Personal expenses paid by an IBCP credit card will not be included in the JSON when a non-offsetting payment is used because it’s not relevant to the company’s accounting record.
Without Offsetting
Example
The user assigns a pre-populated corporate card transaction to the expense report. The transaction is a Hotel expense in the amount of USD 284. The hotel expense consists of a two-night stay at USD 125 per night and the user had a USD 20 dinner after checking in and ordered an in-room movie for USD 14 that the company does not reimburse for. The expense is itemized. The expense is a legitimate business expense with the exception of the in-room movie that the user marks as a non-reimbursable expense on the expense report. The expense report also includes an out-of-pocket cash transaction for parking in the amount of USD 5.
Posting
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Hotel | USD 125 | - |
| Hotel | USD 125 | - |
| Dinner | USD 20 | - |
| Parking | USD 5 | - |
| Credit Card Vendor | - | USD 275 |
With Offsetting
When using offsets the amount due the employee for out-of-pocket expenses is netted (or offset) against the amount marked as personal, resulting in an entry reflecting either the final amount the employee owes the company (assumes personal exceeds out of pocket) or final amount company owes the employee (reduced by any personal amounts).
Posting
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Hotel | USD 125 | - |
| Hotel | USD 125 | - |
| Dinner | USD 20 | - |
| Parking | USD 5 | - |
| Credit Card Vendor | - | USD 275 |
Company Paid Credit Card
CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Consolidated or Verbose Extract)
Example
The employee mistakenly uses the corporate card to pay for tolls (USD 32) and dues (USD 49) expense totaling USD 81. When the corporate card transaction feed populates the company card page the employee must deal with this transaction. The employee assigns the USD 81 corporate card transaction to an expense report, marks it as a non-reimbursable expense and submits the report for approval.
Posting
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Employee Vendor | USD 49 | - |
| Credit Card Clearing | - | USD 49 |
| Credit Card Clearing | USD 49 | - |
| Credit Card Vendor | - | USD 49 |
| Employee Vendor | USD 32 | - |
| Credit Card Clearing | - | USD 32 |
| Credit Card Clearing | USD 32 | - |
| Credit Card Vendor | - | USD 32 |
CBCP Corporate Card Charge with Itemization and Personal Expense (Net Due Employee With Consolidation)
Example
The user assigns a pre-populated corporate card transaction to the expense report. The transaction is a Hotel expense in the amount of USD 284. The hotel expense consists of a two-night stay at USD 125 per night and the user had a USD 20 dinner after checking in and ordered an in-room movie for USD 14 that the company does not reimburse for. The expense is itemized. The expense is a legitimate business expense with the exception of the in-room movie that the user marks as a non-reimbursable expense on the expense report. The expense report also includes an out-of-pocket cash transaction for a taxi at USD 35.
Posting
Posting Record
Expense Report:
| Account | Debit | Credit |
|---|---|---|
| Room Rate | USD 125 | - |
| Room Rate | USD 125 | - |
| Dinner | USD 20 | - |
| Taxi | USD 32 | - |
| Employee Vendor (personal expense) | USD 14 | - |
| Employee Vendor | - | USD 35 |
| Credit Card Clearing | - | USD 284 |
CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Verbose Extract)
Example
The employee mistakenly uses the corporate card to pay for a personal dinner expense of USD 300. When the corporate card transaction feed populates the company card page the employee must deal with this transaction. The employee assigns the USD 300 corporate card transaction to an expense report, marks it as a non-reimbursable expense and submits the report for approval.
Posting
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Employee Vendor | USD 300 | - |
| Credit Card Clearing Account | - | USD 300 |
| Credit Card Clearing Account | USD 300 | - |
| Credit Card Vendor | - | USD 300 |
CBCP Corporate Card Charge with Itemization and Personal Expense (Net Due Employee With No Offsets)
Example
The user assigns a pre-populated corporate card transaction to the expense report. The transaction is a Hotel expense in the amount of USD 284. The hotel expense consists of a two-night stay at USD 125 per night and the user had a USD 20 dinner after checking in and ordered an in-room movie for USD 14 that the company does not reimburse for. The expense is itemized. The expense is a legitimate business expense with the exception of the in-room movie that the user marks as a non-reimbursable expense on the expense report. The expense report also includes an out-of-pocket cash transaction for a taxi at USD 35.
Posting
Posting Record
| Account | Debit | Credit |
|---|---|---|
| Room Rate | USD 125 | - |
| Room Rate | USD 125 | - |
| Dinner | USD 20 | - |
| Taxi | USD 35 | - |
| Employee Vendor (out of pocket) | - | USD 35 |
| Employee Vendor (personal expense) | USD 14 | - |
| Credit Card Vendor | - | USD 284 |
Use Cases Extract Information
- Simple Expense Posting Without Tax
- VAT Handling
- Itemization
- Cash Advances
- Credit Card Items
- Payment via Employee Vendor Account
- Payment via Credit Card Vendor Account (Split Payment)
- Credit Transaction via Credit Card Vendor Account (Split Payment)
- Simple IBCP Corporate Card Charge With Itemization
- IBCP With Personal Expense: No Out-of-Pocket
- IBCP with Personal Expense Where Out-of-Pocket Exceeds the Personal Expense
- IBCP With Personal Expense Where Out-of-Pocket Less Than Personal Expense
- CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Consolidated or Verbose Extract)
- CBCP Corporate Card Charge with Itemization and Personal Expense (Net Due Employee With Consolidation)
- CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Verbose Extract)
- CBCP Corporate Card Charge with Itemization and Personal Expense (Net Due Employee With No Offsets)
Note: The extract file excerpts in this document are a reference point for those developers who have used those files for prior financial integrations. This excerpt is intended to help those developers transition from an extract file to the Financial Integration Service. This allows you to identify what you have been using from the extract file and to locate the same data in the new JSON response. If you have not used the extract file previously, the extract file excerpts can be skipped.
Simple Expense Posting Without Tax
Simple Out-of-Pocket Cash Expense
The Payer in this instance is the company; the Payee is the employee. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The employee will be reimbursed for this transaction.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 8337 | 03/05/2016 | - | Taxi | N | REG | COMPANY | EMPLOYEE | USD 10 | DR | 474230 | - | - |
Simple Out-of-Pocket Cash Credit
The Payer in this instance is the employee; the Payee is the company. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The company will be reimbursed for this transaction.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4178 | 5/28/2019 | Ritz Carlton | Booking Fees (Hotel) | N | REG | EMPLOYEE | COMPANY | USD -50 | CR | 5 | - | - |
Simple Personal Car Mileage Expense
The Payer in this instance is the company; the Payee is the employee. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The employee will be reimbursed for this transaction.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4173 | 5/23/2019 | - | Mileage | N | REG | COMPANY | EMPLOYEE | USD 24.30 | DR | 54 | - | - |
Travel Allowances: Company Specific Rate Greater Than Government Rate
The Payer in this instance is the company; the Payee is the employee. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The employee will be reimbursed for this transaction.
The report entry item will be split into 2 journal entry items: 1st item: amount up to the legal limit, 2nd item: amount above the legal limit.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4196 | 5/28/2019 | - | Fixed Meals | N | REG | COMPANY | EMPLOYEE | 24 EUR | DR | 474230 | - | - |
| 4197 | 5/28/2019 | - | Fixed Meals | N | REG | COMPANY | EMPLOYEE | 26 EUR | DR | 474230 | - | - |
VAT Handling
Expense Posting With Single Tax Item
For the expense line: The Payer in this instance is the company; the Payee is the employee. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The employee will be reimbursed for this transaction. The Tax Code will also appear on this detail line along with the Tax Authority details (label and name).
Tax data: The appearance of the tax data in the extract is governed by the extract options to either include tax information in the same detail line as the entry on which tax is calculated, or to include it as a separate journal line. In this example tax is set to appear as a journal line. The payer is the notional tax authority with the payee as the company (as the reclaimed tax will eventually be paid by the tax authority to the company).
The Journal Amount on the tax detail line can be set to either list the amount eligible to reclaim on either the posted or adjusted (reclaim_posted_amount or reclaim_adjusted_amount). If ‘Adjusted’ the tax reclaim will be calculated on the approved amount (the approved amount may be lower than the claimed (posted) amount). The Tax Source identifies the source of the tax calculation.
The Tax Code can also be set to appear in the Account Code field on the tax detail line (instead of the account code), as shown in this example. The difference between the ‘reclaim’ fields (reclaim_tax_amount, reclaim_posted_amount, reclaim_adjusted_amount) and other tax amount fields (tax_amount, tax_posted_amount, etc.) is that ‘Reclaim’ indicates that these figures are subject to the reclaim percentage specified in the tax configuration.
| [61] entry_id | [64] Entry Transaction Date | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [226] Tax Auth Label | [227] Tax Amount | [228] Tax Posted Amount | [229] Tax Source | [230] reclaim_tax_amount | [231] reclaim_posted_amount | [232] Tax Code | [233] reclaim_domestic |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4282 | 6/5/2019 | Laundry | N | REG | EMPLOYEE | COMPANY | 8.40 EUR | DR | 37 | ILR | 0 | 0 | - | 0 | 0 | V1 | - |
| 4282 | 6/5/2019 | Laundry | N | REG | ILR | COMPANY | 1.60 EUR | CR | V1 | ILR | 1.60 | 1.60 | SYST | 1.60 | 1.60 | V1 | Y |
Itemization
Itemized Expense Items
The Payer in this instance is the company; the Payee is the corporate card vendor. Since it is an itemized expense the Entry Transaction Type is CHD. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. Because this is an IBCP transaction and the payment will be made to the card vendor on behalf of the employee the employee will not receive reimbursement.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4199 | 05/27/2019 | All Suites International | Hotel Room Rate | N | CHD | COMPANY | IBCP CORP | USD 250 | DR | 474230 | - | - |
| 4200 | 05/27/2019 | All Suites International | Hotel Tax | N | CHD | COMPANY | IBCP CORP | USD 50 | DR | 474230 | - | - |
| 4201 | 05/28/2019 | All Suites International | Breakfast | N | CHD | COMPANY | IBCP CORP | USD 25 | DR | 474230 | - | - |
Cash Advances
Paid Cash
Issuance Extract (For reference only. Issuance is not included in the Expense Report FI Document)
There will be one issuance record for each cash advance issued. The issuance record can be identified by the Cash Advance Transaction Type which will always be a ‘1’. The Payer is the Company and the Payee is the Employee. The Journal Amount is a DR transaction in the reimbursement currency. The Cash Advance Amount is the amount of the cash advance in the currency of issuance. The Account Code is the employee cash advance account code, which is an element of the employee profile.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| - | 3/7/2019 | - | - | N | - | COMPANY | EMPLOYEE | USD 7000 | DR | 1009990 | USD 7000 | 1 |
Cash Advance Is Lower Than the Payout Amount
Issuance Extract (For reference only. Issuance is not included in the Expense Report FI Document)
There will be one issuance record for each cash advance issued. The issuance record can be identified by the Cash Advance Transaction Type which will always be a ‘1’. The Payer is the Company and the Payee is the Employee. The Journal Amount is a DR transaction in the reimbursement currency. The Cash Advance Amount is the amount of the cash advance in the currency of issuance. The Account Code is the employee cash advance account code, which is an element of the employee profile.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| - | 6/22/2019 | - | - | N | - | COMPANY | EMPLOYEE | GBP 300 | DR | - | GBP 300 | 1 |
The application of the CA issuance:
The application phase of this case will spawn five records in the standard extract file. Three of the records will cover the three cash out-of-pocket transactions. These three transactions are handled in the same way all cash, out-of-pocket transactions are handled (See the posting record above).
The two additional records are unique to an expense report containing a cash advance. The system will attempt to recover the cash advance amount from the employee by creating credit records against the cash transactions until the total of the cash advance is recovered. In this example, the first cash advance record (entry_id 61) credits the entire GBP 245 of its companion record (entry_id 58). That still leaves GBP 55 of the cash advance unrecovered. So another credit record (entry_id 62) in the amount of GBP 55 will be created against the next companion cash expense record (entry_id 59 and 60). At this point the GBP 300 cash advance has been recovered. The credit journal amounts have the effect of offsetting the total amount due the employee by the amount of the cash advance.
These offset records will have the following characteristics: the Payer is the employee; the Payee is the company. The debit/credit indicator will always be ‘CR’. The Cash Advance Amount field will always contain the total of the cash advances applied to the expense report. The Cash Advance Transaction Type will be a ‘2’. The employee will receive the net of the total cash expenses less the cash advance amount; in this example, GBP 15.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 58 | 6/21/2019 | null | Rental Car | N | REG | COMPANY | EMPLOYEE | GBP 245 | DR | 109 | - | - |
| 59 | 6/21/2019 | Qdoba | Dinner | N | REG | COMPANY | EMPLOYEE | GBP 60 | DR | 105 | - | - |
| 60 | 6/21/2019 | Republic Parking | Parking | N | REG | COMPANY | EMPLOYEE | GBP 10 | DR | 130 | - | - |
| 61 | 6/21/2019 | - | Rental Car | N | REG | EMPLOYEE | COMPANY | GBP -245 | CR | 1009990 | GBP 300 | 2 |
| 62 | 6/21/2019 | - | Dinner & Parking | N | REG | EMPLOYEE | COMPANY | GBP -55 | CR | 1009990 | GBP 300 | 2 |
Cash Advance Is Higher Than the Payout Amount
Issuance Extract (For reference only. Issuance is not included in the Expense Report FI Document)
There will be one issuance record for each cash advance issued. The issuance record can be identified by the Cash Advance Transaction Type which will always be a ‘1’. The Payer is the company and the Payee is the employee. The Journal Amount is a DR transaction in the reimbursement currency. The Cash Advance Amount is the amount of the cash advance in the currency of issuance. The Account Code is the employee cash advance account code, which is an element of the employee profile.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| - | 6/22/2019 | - | - | N | - | COMPANY | EMPLOYEE | GBP 400 | DR | - | GBP 300 | 1 |
The application of the CA issuance:
The application phase of this case will spawn seven records in the standard extract file. Three of the records will cover the three cash out-of-pocket transactions. These three transactions are handled in the same way all cash, out-of-pocket transactions are handled (See the posting record above).
The four additional records are unique to an expense report containing a cash advance. The system will attempt to recover the cash advance amount from the employee by creating credit records against the cash transactions until the total of the cash advance is recovered. In this example, since the total of all expenses does not equal or exceed the cash advance amount, all three expense records have a corresponding offset credit. That still leaves the user GBP 85 short. The cash advance return record in the amount of a GBP 85 credit nets the cash advance amount to zero.
These offset records will have the following characteristics: the Payer is the employee; the Payee is the company. The debit/credit indicator will always be ‘CR’. The Cash Advance Amount field will always contain the total of the cash advances applied to the expense report. The Cash Advance Transaction Type will be a ‘2’. The employee will receive the net of the total cash expenses less the cash advance amount and in the case of a net due to company the employee will be required to submit a cash advance return to retire the balance owed; in this example, GBP 85.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 61 | 6/21/2019 | AVIS | Rental Car | N | REG | COMPANY | EMPLOYEE | GBP 245 | DR | 109 | - | - |
| 62 | 6/21/2019 | MORTONS | Business Meal | N | REG | COMPANY | EMPLOYEE | GBP 60 | DR | 105 | - | - |
| 63 | 6/21/2019 | Republic Parking | Parking | N | REG | COMPANY | EMPLOYEE | GBP 10 | DR | 130 | - | - |
| - | 6/21/2019 | AVIS | Rental Car | N | REG | EMPLOYEE | COMPANY | GBP -245 | CR | 1009990 | GBP 400 | 2 |
| - | 6/21/2019 | MORTONS | Business Meal | N | REG | EMPLOYEE | COMPANY | GBP -60 | CR | 1009990 | GBP 400 | 2 |
| - | 6/21/2019 | Republic Parking | Parking | N | REG | EMPLOYEE | COMPANY | GBP -10 | CR | 1009990 | GBP 400 | 2 |
| - | 6/21/2019 | - | Cash Advance Return | N | REG | EMPLOYEE | COMPANY | GBP -85 | CR | 1009990 | GBP 400 | 2 |
Credit Card Types
Payment via Employee Vendor Account
The Payer in this instance is the company; the Payee is the employee. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. The employee will be reimbursed for this transaction.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 8337 | 03/05/2016 | - | Taxi | N | REG | COMPANY | EMPLOYEE | USD 10 | DR | 474230 | - | - |
Payment via Credit Card Vendor Account (Split Payment)
The Payer in this instance is the company; the Payee is the corporate card vendor. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. Because this is an IBCP transaction and the payment will be made to the card vendor on behalf of the employee the employee will not receive reimbursement.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 36 | 4/7/2008 | DOLLAR | Rental Car | N | REG | COMPANY | IBCP CORP | USD 56.10 | DR | 11 | - | - |
Credit Transaction via Credit Card Vendor Account (Split Payment)
The Payer in this instance is the corporate card vendor; the Payee is the company. Since it is not an itemized expense the Entry Transaction Type is REG. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. Because this is an IBCP transaction and the payment/credit will be made to the card vendor on behalf of the employee the employee will not receive reimbursement (or be required to pay the balance).
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4225 | 5/27/2019 | ALASKA AIRLINE | Airfare | N | REG | COPD | COMPANY | USD -349 | CR | 474230 | - | - |
Simple IBCP Corporate Card Charge With Itemization
The Payer in this instance is the company; the Payee is the corporate card vendor. Since it is an itemized expense the Entry Transaction Type is ‘CHD’. Because it is a legitimate business expense the ‘Is Personal’ flag is set to ‘N’. Because this is an IBCP transaction and the payment will be made to the card vendor on behalf of the employee the employee will not receive reimbursement.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4199 | 05/27/2019 | All Suites International | Hotel Room Rate | N | CHD | COMPANY | IBCP CORP | USD 250 | DR | 474230 | - | - |
| 4200 | 05/27/2019 | All Suites International | Hotel Tax | N | CHD | COMPANY | IBCP CORP | USD 50 | DR | 474230 | - | - |
| 4201 | 05/28/2019 | All Suites International | Breakfast | N | CHD | COMPANY | IBCP CORP | USD 25 | DR | 474230 | - | - |
IBCP With Personal Expense: No Out-of-Pocket
The Payer in this instance is the company; the Payee is the corporate card vendor. Since it is an itemized expense the Entry Transaction Type is CHD. Because this is an IBCP transaction and the payment will be made to the card vendor on behalf of the employee the employee will not receive reimbursement. Because the entry marked as personal is not a legitimate/approved business expense, payment to the card vendor is the responsibility of the employee. The amount is not reimbursable to the employee and the expense amount should not be posted with other business transactions. Therefore, the personal amount is not included in the financial posting JSON.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4220 | 05/29/2019 | All Suites International | Hotel Room Rate | N | CHD | COMPANY | IBCP | USD 250 | DR | 474230 | - | - |
| 4221 | 05/29/2019 | All Suites International | Hotel Tax | N | CHD | COMPANY | IBCP | USD 50 | DR | 474230 | - | - |
| 4222 | 05/30/2019 | All Suites International | Breakfast | Y | REG | EMPL | COMPANY | USD 25 | DR | 199999 | - | - |
IBCP with Personal Expense Where Out-of-Pocket Exceeds the Personal Expense
The Payer for both transactions is the company. The Payee is the corporate card vendor for the legitimate business expenses on the hotel transaction (the hotel expenses and the dinner expense). Because the reimbursement method is IBCP w/offsets, the card vendor will also be the payee for the personal expenses on the hotel transaction up to the total amount of out-of-pocket cash expense submitted on this expense report. Since the non-reimbursable in-room movie expense (USD 14) is less than the total out-of-pocket cash expenses (USD 35) owed to the employee, the company will pay the USD 14 personal expense to the card vendor and offset that amount against the USD 35 owed to the employee. Thus the employee will only receive USD 21 of the USD 35 taxi expense. In this case there were enough out-of-pocket cash expenses to offset the non-reimbursable expenses so there is a net due to the employee for this expense report.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 89 | 7/15/2019 | MARRIOTT | Hotel | N | CHD | COMPANY | IBCP CORP | USD 125 | DR | 99999 | - | - |
| 90 | 7/16/2019 | MARRIOTT | Hotel | N | CHD | COMPANY | IBCP CORP | USD 125 | DR | 99999 | - | - |
| 91 | 7/15/2019 | MARRIOTT | Dinner | N | CHD | COMPANY | IBCP CORP | USD 20 | DR | 600 | - | - |
| 93 | 7/16/2019 | Taxi | Local Trans | N | REG | COMPANY | EMPLOYEE | USD 21 | DR | 88888 | - | - |
| 93 | 7/16/2019 | Taxi | Local Trans | N | REG | COMPANY | IBCP CORP | USD 14 | DR | 88888 | - | - |
IBCP With Personal Expense Where Out-of-Pocket Is Less Than Personal Expense
The Payer for both transactions is the company. The Payee is the corporate card vendor for the legitimate business expenses on the Hotel transaction (the Hotel expenses and the Dinner expense). Because the reimbursement method is IBCP w/offsets, the card vendor will also be the payee for the personal expenses on the Hotel transaction up to the total amount of out-of-pocket cash expense submitted on this expense report. Since the non-reimbursable in-room movie expense (USD 14) is greater than the total out-of-pocket cash expenses (USD 5) owed to the employee, the company will pay only USD 5 of the USD 14 personal expense to the card vendor and offset that amount against the USD 5 owed to the employee. Thus the employee will not receive any reimbursement and will personally owe the card vendor for the difference between the USD 5 paid by the company on his behalf and the USD 14 charge, or USD 9. In this case there were not enough out-of-pocket cash expenses to offset the non-reimbursable expenses so the employee is responsible to make up the difference with the card vendor.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 95 | 7/15/2019 | MARRIOTT | Hotel | N | CHD | COMPANY | IBCP CORP | USD 125 | DR | 99999 | - | - |
| 98 | 7/16/2019 | MARRIOTT | Hotel | N | CHD | COMPANY | IBCP CORP | USD 125 | DR | 99999 | - | - |
| 96 | 7/16/2019 | MARRIOTT | Dinner | N | CHD | COMPANY | IBCP CORP | USD 20 | DR | 600 | - | - |
| 99 | 7/16/2019 | PARKING | Parking | N | REG | COMPANY | IBCP CORP | USD 5 | DR | 40 | - | - |
CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Consolidated or Verbose Extract)
The extract produces two records for this single transaction. One record addresses payment that must be made to the card vendor by the company. The Payer is the company. The Payee is the corporate card vendor. The amount is a debit of USD 49 to the clearing account. Since there are no employee out-of-pocket expenses on this expense report there is nothing to offset the amount that the employee owes the company. Therefore, a separate record is created to address the net due company condition. In this record the Payer is the employee and the Payee is the company. The amount is a credit of USD 49 to the clearing account. The company’s financial system must have a process for dealing with this employee receivable condition. The CT&E system will not “carry over” this net due company amount to subsequent expense reports.
The company will pay the credit card vendor for the full amount due the card and retain a corresponding employee receivable (most likely represented as a debit in the employee’s vendor account. This allows natural offsetting to occur if there are subsequent amounts due the employee posted to their vendor record in the future.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| - | 6/1/2016 | - | Dues | Y | REG | EMPLOYEE | COMPANY | USD -49 | CR | cbcp180 | - | - |
| - | 6/1/2016 | - | Dues | Y | REG | COMPANY | CBCP CORP | USD 49 | DR | cbcp180 | - | - |
| - | 6/1/2016 | - | Tolls | Y | REG | EMPLOYEE | COMPANY | USD -32 | CR | compaid374 | - | - |
| - | 6/1/2016 | - | Tolls | Y | REG | COMPANY | CBCP CORP | USD 32 | DR | compaid374 | - | - |
CBCP Corporate Card Charge with Itemization and Personal Expense (Net Due Employee With Consolidation)
The Payer for both transactions is the company. The Payee is the corporate card vendor for the full amount of the hotel transaction (the company owes the card vendor for the entire amount of the transaction, including the non-reimbursable in-room movie) and the employee for the balance of the taxi expense after the offset is taken for the in-room movie portion of the corporate card transaction. The employee would normally be reimbursed for the full USD 35 out-of-pocket taxi expense but, because a portion of the company paid corporate card transaction was not a legitimate business expense, the system reduces the amount due to the employee by the amount of the non-reimbursable expense. In this case there was enough out-of-pocket cash expenses to offset the non-reimbursable expenses so there is a net due to the employee for this expense report.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4252 | 6/4/2019 | MARRIOTT | Hotel | N | CHD | COMPANY | CBCP CORP | USD 125 | DR | 474230 | - | - |
| 4253 | 6/3/2019 | MARRIOTT | Hotel | N | CHD | COMPANY | CBCP CORP | USD 125 | DR | 7271001 | - | - |
| 4254 | 6/3/2019 | MARRIOTT | Dinner | N | CHD | COMPANY | CBCP CORP | USD 20 | DR | 474230 | - | - |
| 4291 | 5/29/2019 | Taxi | Local Trans | N | REG | COMPANY | EMPLOYEE | USD 35 | DR | 474230 | - | - |
| 4255 | 6/5/2019 | MARRIOTT | In-room movie | Y | REG | COMPANY | CBCP CORP | USD 14 | DR | 199999 | - | - |
CBCP Corporate Card Charge for Entirely Personal Expense (Net Due Company With Verbose Extract)
The extract produces two records for this single transaction. One record addresses payment that must be made to the card vendor by the company. The Payer is the company. The Payee is the corporate card vendor. The amount is a debit of USD 300 to the clearing account. The second record is created to address the net due company condition. In this record the Payer is the employee and the Payee is the company. The amount is a credit of USD 300 to the clearing account. The company’s financial system must have a process for dealing with this employee receivable condition. The CT&E system will not “carry over” this net due company amount to subsequent expense reports.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| - | 9/1/2016 | Cheesecake Factory | Dinner | Y | REG | EMPLOYEE | COMPANY | USD -300 | CR | - | - | - |
| - | 9/1/2016 | Cheesecake Factory | Dinner | Y | REG | COMPANY | CBCP CORP | USD 300 | DR | - | - | - |
CBCP Corporate Card Charge with Itemization and Personal Expense (Net Due Employee With No Offsets)
The records are slightly different from the previous example where offsets are built into the extract. In this case, where there are no built-in offsets, each record is distinct and the offset will need to be calculated in the client’s bridge program. The Payer for both transactions is the company except for the personal portion of the Hotel expense. The personal amount of USD 14 is represented with two distinct records. One record addresses the amount due to the corporate card vendor to ensure that the full amount of the otel transaction (including the personal amount) is paid to the card vendor. A second offsetting record addresses the same personal amount that the employee owes back to the company. In the first record, the company is the Payer and the Payee is the corporate card vendor for the USD 14 non-reimbursable in-room movie). In the second record the employee is the Payer and the Payee is the company for the credit amount of the USD 14 non-reimbursable in-room movie. The full USD 35 out-of-pocket taxi expense is handled as a normal out-of-pocket cash expense with the company being the Payer and the employee being the Payee. The client’s bridge program will need to summarize the two records (+USD 35 taxi and -USD 14 in-room movie) to arrive at the USD 21 due to the employee.
| [61] entry_id | [64] Entry Transaction Date | [70] Vendor Name | [63] Expense Type | [68] Is Personal | [62] Entry Transaction Type | [163] Payer Payment Type | [165] Payee Payment Type | [169] Journal Amount | [168] Debit Credit | [167] Account Code | [177] Cash Advance Amount | [185] Cash Advance Transaction Type |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 4336 | 6/6/2019 | MARRIOTT | Hotel | N | CHD | COMPANY | CBCP CORP | USD 125 | DR | 474230 | - | - |
| 4337 | 6/7/2019 | MARRIOTT | Hotel | N | CHD | COMPANY | CBCP CORP | USD 125 | DR | 474230 | - | - |
| 4338 | 6/8/2019 | MARRIOTT | Dinner | N | CHD | COMPANY | CBCP CORP | USD 20 | DR | 474230 | - | - |
| 4339 | 6/8/2019 | MARRIOTT | In-Room Movie | Y | CHD | COMPANY | CBCP CORP | USD 14 | DR | 199999 | - | - |
| 4339 | 6/8/2019 | MARRIOTT | In-Room Movie | Y | CHD | EMPLOYEE | COMPANY | USD 14 | CR | 199999 | - | - |
| 4340 | 6/8/2019 | Taxi | Local Trans | N | REG | COMPANY | EMPLOYEE | USD 35 | DR | 474230 | - | - |
Schemas
Expense
Expense - Employee
| Name | Type | Format | Description |
|---|---|---|---|
employeeCustom1Code through employeeCustom21Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
employeeCustom1Value through employeeCustom21Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters. |
employeeFirstName |
String |
- | Alphanumeric. First name of employee. Maximum length 32 characters. |
employeeId |
String |
- | Alphanumeric. Employee ID often also serves as the employee’s Vendor ID for AP system integrations or payroll ID for payroll integrations. Maximum length 128 characters. |
employeeLastName |
String |
- | Alphanumeric. Last name of employee. Maximum length 32 characters. |
employeeMI |
String |
- | Alphanumeric. Middle initial of employee. Maximum length 1 character. |
employeeOrgUnit1Code through employeeOrgUnit6Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
employeeOrgUnit1Value through employeeOrgUnit6Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters. |
Expense - Report
| Name | Type | Format | Description |
|---|---|---|---|
cashAdvanceReturnsAmount |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Currency. Amount of cash advance returned. |
employeeCurrencyAlphaCode |
String |
3-letter ISO 4217 alpha code. | Alphanumeric. Reimbursement currency. |
homeCountryCode |
String |
ISO 3166-1 alpha-2 country code. | Alphanumeric. The report country. Example: United States is US. |
isTest |
String |
Y/N | Signifies if this report belongs to a test user in system. Y = test user, N = not a test user. |
ledgerCode |
String |
- | Alphanumeric. External accounting system ID. Maximum length 20 characters. |
payrollPayIndicator |
String |
Y/N | This field indicates whether the expense group the report user belongs to is configured to reimburse employees using Payroll. |
payrollPaymentClearingAccountCode |
String |
- | Alphanumeric. SAP customers who reimburse their employees via Payroll need to capture a payroll clearing account code as part of the accounting entry during the financial posting process. Maximum length 128 characters. |
reportCreationDate |
String |
yyyy-mm-ddThr:min:sec.msZ | Date the report was created. Maximum length 24 characters. |
reportCustom1Code through reportCustom20Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
reportCustom1Value through reportCustom20Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters. |
reportEndDate |
String |
yyyy-mm-ddThr:min:sec.msZ | End date from the report header. Can be imported from trip data or manually entered. |
reportId |
String |
Unique (across all SAP Concur clients) 32 character alphanumeric. | Alphanumeric. Often used as a voucher number when integrating across AP systems. |
reportKey |
Number |
- | A unique ID (within a single SAP Concur client's company) generated by the system. An alternative to the reportId. Starts with 1 and increments with each expense report. Maximum length 11 characters. |
reportName |
String |
- | Alphanumeric. Report name assigned by employee. Maximum length 40 characters. |
reportOrgUnit1Code through reportOrgUnit20Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. The second segment in the fully qualified GL string should use Org Unit 2, except the natural account field. The natural account data is stored in column 167 of the SAE. Maximum length 48 characters. |
reportOrgUnit1Value through reportOrgUnit20Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters. |
reportPaymentProcessingDate |
String |
yyyy-mm-ddThr:min:sec.msZ | The date that the report completed all approvals and was ready to be extracted for payment. Maximum length 24 characters. |
reportStartDate |
String |
- | Report start date. Maximum length 24 characters. |
reportSubmitDate |
String |
- | Date/time the employee submitted the report for approval. Maximum length 24 characters. |
reportUserDefinedDate |
String |
- | Custom date/time specified by user. Maximum length 24 characters. |
revisionNumber |
Number |
- | Report revision number. This will be used to track changes made to posted expenses. Default value is 1. Maximum length 32 characters. |
totalApprovedAmount |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Total approved amount of the report. |
versionId |
Number |
- | The version of the FI Document, which is the same as the version of the API endpoint. Maximum length 32 characters. |
Expense - expenseEntry
| Name | Type | Format | Description |
|---|---|---|---|
cardAccountID |
String |
- | Alphanumeric. ID for the card account. This can be used by the receiving system to condense transactions associated with this card. Maximum length 32 characters. |
cardProgramTypeCode |
String |
- | Alphanumeric. The code used to identify the card’s program type. Maximum length 5 characters. |
cardStatementPeriodEndDate |
String |
yyyy-mm-ddThr:min:sec.msZ | The date of the end of the statement period. Maximum length 24 characters. |
cardStatementPeriodStartDate |
String |
yyyy-mm-ddThr:min:sec.msZ | The date of the start of the statement period. Maximum length 24 characters. |
cardTransactionAmount |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Currency. Amount of the charge in the spend currency. |
cardTransactionCurrency |
String |
ISO 4217 3-letter alpha code. | Alphanumeric. Currency code for the spend currency. |
cardTransactionID |
String |
- | Reference number from the credit card vendor. Maximum length 32 characters. |
cardTransactionPostedAmount |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Amount of the charge in the billing currency of the card. |
cardTransactionPostedCurrency |
String |
ISO 4217 3-letter alpha code. | Alphanumeric. Currency code for the card billing currency. |
clearingAccountCode |
String |
- | Alphanumeric. Contains the expense type account code. - or - If a CBCP Personal expense, the company card clearing account code. - or - If charge is tied to a Statement Report, and accounting code is set for Company Billed card account, the card's accounting code as specified in the Account Code field when creating or editing a CBS account. Maximum length 20 characters. |
entryApprovedAmount |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Currency. Amount approved in the reimbursement currency. |
entryCountryCode |
String |
2-character country code. | Alphanumeric. Report entry country code. |
entryCountrySubCode |
String |
- | Alphanumeric. Report entry country sub code. Maximum length 6 characters. |
entryCurrAlphaCode |
String |
ISO 4217 3-letter alpha code. | Alphanumeric. Currency ISO alpha code for the spend currency if not an imported credit card or the invoice currency if this is a credit card. Maximum length 4 characters. |
entryCustom1Code through entryCustom40Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
entryCustom1Value through entryCustom40Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters. |
entryDate |
String |
yyyy-mm-ddThr:min:sec.msZ | Date that this expense was incurred (when the money was spent or credit card receipt date). |
entryDescription |
String |
- | Alphanumeric. Expense description as entered by the employee. Maximum length 64 characters. |
entryElectronicReceiptId |
String |
- | GUUID. Electronic receipt ID. Maximum length 24 characters. |
entryExchangeRate |
Number |
- | Rate used to convert from the report entry (spend) currency to the report (reimbursement) currency. Maximum length 23 characters. |
entryExchangeRateDirection |
String |
M/D | Alphanumeric. The direction of the exchange rate conversion. Either: M = Multiply or D = Divide. |
entryId |
String |
- | Report entry sync GUUID unique key. Maximum length 32 characters. |
entryIsBillable |
String |
Y/N | Yes or no is the expense billable. |
entryIsPersonal |
String |
Y/N | Yes or no is the expense personal. |
entryLocationCityName |
String |
- | Alphanumeric. Report entry location city name. Maximum length 64 characters. |
entryLocationName |
String |
- | Alphanumeric. Report entry location name. Maximum length 64 characters. |
entryOrgUnit1Value through entryOrgUnit6Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters. |
entryOrgUnit1Code through entryOrgUnit6Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
entryReceiptId |
String |
- | GUUID. Non-electronic receipt image. Maximum length 32 characters. |
entryReceiptType |
String |
T/R/N | Alphanumeric. One of these: T = Tax receipt, R = Regular receipt, or N = No receipt. |
entrySupplierTaxID |
String |
- | Alphanumeric. Report entry XML receipt supplier tax ID. Maximum length 64 characters. |
entryUuid |
String |
- | Report Entry XML Receipt UUID. Maximum length 32 characters. |
entryVendorCode |
String |
- | Alphanumeric. Vendor name list short code. Maximum length 32 characters. |
entryVendorDescription |
String |
- | Alphanumeric. Vendor description. Maximum length 64 characters. |
expensePayIndicator |
String |
Either: 1 = Expense Pay or blank = not Expense Pay. | Indicates whether Expense Pay reimbursed this journal entry. |
expenseTypeCode |
String |
- | Alphanumeric. Code for the expense type. Maximum length 5 characters. |
expenseTypeName |
String |
- | Alphanumeric. Expense type name. Maximum length 64 characters. |
legacyEntryId |
Number |
- | Legacy report entry key. Maximum length 11 characters. |
liabilityAccountCode |
String |
- | Alphanumeric. The liability account code assigned to the funding account paying this entry. Maximum length 48 characters. |
offsetPayType |
String |
Y/N | Use Offsets. Y = Yes, N= No. |
reportEntryPatKey |
String |
- | Alphanumeric. Report Entry Payment Code. Maximum length 4 characters. |
Expense - Allocation
| Name | Type | Format | Description |
|---|---|---|---|
allocationCustom1Code through allocationCustom20Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
allocationCustom1Value through allocationCustom20Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. If configured as a list, this field contains the name of the list item. Maximum length 64 characters. |
allocationId |
String |
- | GUUID. System-generated unique key for this allocation record. Maximuml length 32 characters. |
allocationPercentage |
Number |
- | Percent of the report entry assigned to this allocation record. Maximum length 11 characters. |
Expense - Journal
| Name | Type | Format (length) | Description |
|---|---|---|---|
accountingTransactionType |
String |
- | Alphanumeric. This is the Intuit QuickBooks specific transaction value. It will be null or a value (GJ, CC, or BILL) depending on if it’s a journalpayee or journalpayer. This determines if a transaction should be posted as Bill or Credit Card in QuickBooks. Maximum length 24 characters. |
amountGrossCard |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Amount due to the company card of either CBCP or IBCP type for this detail row. |
amountNetOfReclaim |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Currency. Gross Journal amount subtracting reclaimable tax. Or the Net Journal amount adding non-reclaimable tax. |
amountNetOfTax |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Currency. Allocated net of reclaim tax. You get this by starting from the net and adding the tax that is not reclaimable, or starting with the gross and subtracting reclaimable. |
amountTax |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Currency. This is the Gross Journal amount subtracting the total Tax amount. |
cardTransactionReferenceNumber |
Number |
- | Reference number from the credit card vendor. Maximum length 64 characters. |
journalAccountCode |
String |
- | Alphanumeric. Contains the expense type account code. - or - If a CBCP Personal expense, the company card clearing account code. - or - If charge is tied to a Statement Report, and accounting code is set for Company Billed card account, the card's accounting code as specified in the Account Code field when creating or editing a CBS account. Maximum length 48 characters. |
journalPayee |
String |
- | Alphanumeric. Payment code name for the payee. Maximum length 4 characters. |
journalPayer |
String |
- | Alphanumeric. Payment code name for the payer. Maximum length 4 characters. |
taxGuid |
String |
- | GUUID. Unique identifier associated with the report entry tax allocation. Maximum length 32 characters. |
Expense - cashAdvanceApplication
| Name | Type | Format | Description |
|---|---|---|---|
cashAdvanceApplicationAmount |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Currency. Cash advance utilized amount. |
cashAdvanceClearingAccountCode |
String |
- | Alphanumeric. The Account Code is the clearing account code which was configured for the employee in the profile. Maximum length 48 characters. |
cashAdvanceId |
String |
- | GUUID. Unique system ID assigned to the cash advance. Maximum length 32 characters. |
cashAdvanceTransactionType |
Number |
- | Type of transaction: 1 = Issue or return to administrator, 2 = Application, including cash advance return expense within a report, or 3 = System cash advance, from balance carry forward. |
Schemas - Invoice
Invoice - requestHeader
| Name | Type | Format | Description |
|---|---|---|---|
amountNetInvoice |
Number |
- | The invoice total amount minus the shipping and tax amounts. Maximum length 23 characters. |
amountShippingTotal |
Number |
- | The value for the shipping amount header field. Maximum length 23 characters. |
amountTax |
Number |
- | The total amount of tax on a given invoice. Maximum length 23 characters. |
amountVAT1 through amountVAT4 |
Number |
23 | The individual total VAT amounts for the invoice. Maximum length 23 characters. |
clearingAccountCode |
String |
- | Contains the expense type account code. - or - If a CBCP Personal expense, the company card clearing account code. - or - If charge is tied to a Statement Report, and accounting code is set for Company Billed card account, the card's accounting code as specified in the Account Code field when creating or editing a CBS account. Maximum length 20 characters. |
currencyAlphaCode |
String |
ISO 4217 3-letter alpha code. | Currency ISO alpha code for the spend currency if not an imported credit card or the invoice currency if this is a credit card. |
deliverySlipNumber |
String |
- | Delivery slip number of the receipt which is associated to the invoice line item. Maximum length 256 characters. |
discountPercentage |
Number |
Percentage | Percent value that defines the amount of discount that would be applied. |
discountTermsDays |
Number |
- | Numeric value defining the discount term day amount. Maximum length 3 characters. |
invoiceDate |
String |
YYYY-MM-DD | Date of the invoice. |
invoicePayIndicator |
String |
Y/N- | Signifies if this report belongs to a test user in system. |
invoiceReceivedDate |
String |
YYYY-MM-DD | The date on which the invoice was received. |
isTest |
String |
Y/N | Signifies if this report belongs to a test user in system. |
ledgerCode |
String |
- | External accounting system ID. Maximum length 20 characters. |
ledgerName |
String |
- | The general ledger tied to the invoice. Maximum length 100 characters. |
multiplePurchaseOrder |
String |
Y/N | Defines whether or not multiple purchase orders are tied to the invoice. |
netPaymentTermDays |
Number |
- | Numeric value defining the payment term day amount. Maximum length 3 characters. |
paymentDueDate |
String |
YYYY-MM-DD | The date the payment is due for a given invoice. |
payMethodType |
String |
Drop Down Selector. Valid format options include: ACH, client paid, check, PAYPVD, wire, card, or VCHER. | The method used to pay the invoice, as of the point in time the extract is run. NOTE: It is possible for the method to be changed or updated post-extract through either the Payment Confirmation import (if the client controls payments), or through Invoice Pay (using Payment Manager). |
postingDate |
String |
YYYY-MM-DD | The date the invoice will be posted to the ERP system. |
processCompleteDate |
String |
YYYY-MM-DD | The date the invoice was processed. |
reqKey |
Number |
Integer | An integer that uniquely defines this invoice in SAP Concur. This is the value that the Invoice Confirmation Import uses to match to this particular invoice. |
requestCreationDate |
String |
YYYY-MM-DD | The date the invoice was originally saved. |
requestCustom1Code through requestCustom24Code |
CustomField |
The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. | |
requestCustom1Value through requestCustom24Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
requestDescription |
String |
- | The invoice’s description. Maximum length 250 characters. |
requestId |
String |
- | The unique identification assigned to the invoice. Maximum length 20 characters. |
requestOrgUnit1Code through requestOrgUnit6Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
requestOrgUnit1Value through requestOrgUnit6Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
requestTitle |
String |
- | The invoice name. Maximum length 100 characters. |
requestTotal |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | The sum of all Line Item Amounts plus Shipping Amount and Tax Amount for the invoice. |
revisionNumber |
Number |
- | Invoice revision number. Default value is 1. Maximum length 32 characters. |
submitDate |
String |
YYYY-MM-DD | Date/time the employee submitted the invoice for approval. |
vendorInvoiceNumber |
String |
- | The invoice number assigned by the vendor. Maximum length 50 characters. |
versionId |
String |
- | The version of the FI Document, which is the same as the version of the API endpoint. Maximum length 32 characters. |
Invoice - ownerEmployee
| Name | Type | Format | Description |
|---|---|---|---|
employeeCustom1Code through employeeCustom21Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
employeeCustom1Value through employleeCustom21Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
employeeFirstName |
String |
- | First name of employee. Maximum length 32 characters. |
employeeId |
String |
- | Employee ID often also serves as the employee’s Vendor ID for AP system integrations or Payroll ID for Payroll integrations. Maximum length 48 characters. |
employeeLastName |
String |
- | Last name of employee. Maximum length 32 characters. |
employeeMI |
String |
- | Middle initial of employee. Maximum length 1 character. |
employeeOrgUnit1Value through employeeOrgUnit6Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
Invoice - Vendor
| Name | Type | Format | Description |
|---|---|---|---|
vendorCode |
String |
- | The financial system's code for this vendor. Maximum length 23 characters. |
vendorContactFirstName |
String |
- | Buyer contact for the vendor record’s first name. Maximum length 255 characters. |
vendorContactLastName |
String |
- | Buyer contact for the vendor record’s last name. Maximum length 255 characters. |
vendorName |
String |
- | The financial system's name for this vendor. Maximum length 255 characters. |
vendorRemitToAddressCode |
String |
Less than or equal to 64. | The financial system's code for this address. |
Invoice - lineItem
| Name | Type | Format | Description |
|---|---|---|---|
allocationAccountCode |
String |
- | The Account Code for the Allocation related to this Journal Entry. Maximum length 20 characters. |
allocationCustom1Code through allocationCustom20Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
allocationCustom1Value through allocationCustom20Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
allocationKey |
Number |
- | System-generated unique key for this allocation record. Maximum length 13 characters. |
allocationPercentage |
Number |
- | Percent of the report entry assigned to this allocation record. Maximum length 64 characters. |
journal |
String |
- | Container for journal entries tied to the allocation. Maximum length 48 characters. |
accountCode |
Number |
- | The financial system accounting code value tied to the invoice line. Maximum length 20 characters. |
amountGross |
Number |
- | The gross amount (total amount) of the invoice line item. Maximum length 23 characters. |
amountNet |
Number |
- | The net amount of the invoice line item not including shipping and tax. Maximum length 23 characters. |
amountShipping |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | The value for the Shipping Amount header field. Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. |
expenseTypeCode |
String |
- | Code for the expense type so a value that isn’t language dependent is returned. Maximum length is 7 characters. |
expenseTypeName |
String |
- | Expense type name. Maximum length 64 characters. |
externalLineItemId |
String |
- | The PO Line item associated with to the Invoice. Maximum length 100 characters. |
lineItemCode |
String |
- | The Primary Key value for the expense type. Maximum length 7 characters. |
lineItemCustom1Code through lineItemCustom20Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
lineItemCustom1Value through lineItemCustom20Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
lineItemDeliverySlipNumber |
String |
- | Delivery Slip Number of the receipt which is associated to the invoice line item. Maximum length 256 characters. |
lineItemDescription |
String |
- | The description of the goods or services being purchased on the individual invoice line. Maximum length 255 characters. |
lineItemPurchaseOrderNumber |
String |
- | The purchase order number associated with the invoice line item (for a multiple purchase order-based invoice), or the purchase order number associated with the header (for a single purchase order-based invoice). Maximum length 10 characters. |
lineItemQuantity |
String |
- | The quantity of the line item. Maximum length 23 characters. |
lineItemSequenceOrder |
Number |
Integer | Line item number for the line item related to this Journal Entry. Value is dynamically generated by the system based on the number of lines. |
lineItemUnitPrice |
Number |
- | The quantity unit price for the item being purchased. Maximum length 23 characters. |
poLineNumber |
Number |
- | The PO line item number associated to the payment request. Maximum length 48 characters. |
receiptNumber |
Number |
- | The Goods Receipt number. Maximum length 256 characters. |
receiptQuantity |
Number |
- | The Goods Received quantity. Maximum length 23 characters. |
receiptItemID |
Number |
- | The ID of the Goods Receipt tied to the Invoice and PO Line. Maximum length 48 characters. |
Invoice - Tax
| Name | Type | Format | Description |
|---|---|---|---|
amountTax |
Number |
- | The taxation amount that exists on the invoice line. Maximum length 23 characters. |
taxCode |
String |
- | Tax code assigned to this tax authority for the expense type entered on the expense entry. Maximum length 20 characters. |
taxField |
String |
- | Defines which database field the tax resides in. Maximum length 20 characters. |
Cash Advance
Cash Advance - employeeData
| Name | Type | Format | Description |
|---|---|---|---|
employeeCustom1Code through employeeCustom21Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
employeeCustom1Value through employeeCustom21Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 64 characters. |
employeeFirstName |
String |
- | Alphanumeric. First name of employee. Maximum length 32 characters. |
employeeId |
String |
- | Alphanumeric. Employee ID often also serves as the employee’s Vendor ID for AP system integrations or Payroll ID for Payroll integrations. Maximum length 128 characters. |
employeeLastName |
String |
- | Alphanumeric. Last name of employee. Maximum length 32 characters. |
employeeMI |
String |
- | Alphanumeric. Middle initial of employee. Maximum length 1 character. |
employeeOrgUnit1Code through employeeOrgUnit6Code |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 48 characters. |
employeeOrgUnit1Value through employeeOrgUnit6Value |
CustomField |
- | The details from the custom fields. These fields may not have data, depending on the configuration. Maximum length 64 characters. |
Cash Advance - cashAdvanceData
| Name | Type | Format | Description |
|---|---|---|---|
cardAccountID |
String |
- | Alphanumeric. ID will be used initially by the receiving system to “condense” transactions associated with this card. It will also be used to retrieve the card number in a separate API call. Maximum length 32 bytes. |
cardTransactionAmount |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Currency. Amount of the charge in the spend currency. |
cardTransactionCurrency |
String |
ISO 4217 3-letter alpha code. | Alphanumeric. Currency code for the spend currency. |
cardTransactionID |
String |
- | Alphanumeric. Calculated value assigned to this card entry during the import process. Maximum length 32 characters. |
cardTransactionPostedAmount |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Currency. Amount of the charge in the billing currency of the card. |
cardTransactionPostedCurrency |
String |
ISO 4217 3-letter alpha code. | Alphanumeric. Currency code for the card billing currency. |
cashAdvanceId |
String |
- | GUUID. Unique system ID assigned to the cash advance. Maximum length 32 characters. |
clearingAccountCode |
String |
- | Alphanumeric. Contains the expense type account code. - or - If a CBCP Personal expense, the company card clearing account code. - or - If charge is tied to a Statement Report, and accounting code is set for Company Billed card account, the card's accounting code as specified in the Account Code field when creating or editing a CBS account. Maximum length 20 characters. |
countryCode |
String |
ISO 3166-1 alpha-2 country code. | Alphanumeric. The report country. Example: United States is US. |
countrySubCode |
String |
- | Alphanumeric. Report entry country sub code. Maximum length 6 characters. |
currencyAlphaCode |
String |
ISO 4217 3-letter alpha code. | Alphanumeric. Currency ISO alpha code for the spend currency if not an imported credit card or the invoice currency if this is a credit card. |
currencyNumCode |
String |
ISO 4217 3-letter alpha code. | Alphanumeric. Currency code for the transaction currency using ISO number code. |
employeeCurrencyAlphaCode |
String |
ISO 4217 3-letter alpha code. | Alphanumeric. Reimbursement currency. |
exchangeRate |
Number |
- | Rate used to convert from the report entry (spend) currency to the report (reimbursement) currency. Maximum length 23 characters. |
expensePayIndicator |
String |
Y/N | Indicates whether Expense Pay reimbursed this journal entry. Either: Y = Expense Pay or N = not Expense Pay. |
issuedDate |
String |
yyyy-mm-ddThr:min:sec.msZ | Date of issue. |
isTest |
String |
Y/N | Signifies if this report belongs to a test user in system. |
entrylocationName |
String |
- | Alphanumeric. The report entry location name (for example, city name). Maximum length 64 characters. |
name |
String |
- | Alphanumeric. Cash advance request name. Maximum length 40 characters. |
paymentMethod |
String |
0 = Non-Expense Pay method used for disbursement or 1 = Expense Pay method used for disbursement. | Alphanumeric. The method used, either Expense Pay or Other, used for disbursement of the cash advance. |
purpose |
String |
- | Alphanumeric. Describes the purpose of cash advance issued. Maximum length 2,000 characters. |
requestAmount |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Currency. For issue journal record, the total amount of the cash advance in the cash advance transaction currency. |
requestDate |
String |
yyyy-mm-ddThr:min:sec.msZ | Date of cash advance request from the detailed cash advance record. |
requestedDisbursementDate |
String |
yyyy-mm-ddThr:min:sec.msZ | Cash advance disbursement date. |
transactionType |
String |
1 = Issue or Return to Administrator, 2 = Application, including Cash Advance Return expense within a report, or 3 = System Cash advance, from balance carry forward. | Alphanumeric. Type of transaction. |
travelEndDate |
String |
yyyy-mm-ddThr:min:sec.msZ | The last day of the trip on the assigned travel request itinerary. |
travelStartDate |
String |
yyyy-mm-ddThr:min:sec.msZ | The first day of the trip on the assigned travel request itinerary. |
Cash Advance - journalData
| Name | Type | Format | Description |
|---|---|---|---|
accountCode |
String |
- | Alphanumeric. Contains the expense type account code. - or - If a CBCP Personal expense, the company card clearing account code. - or - If charge is tied to a Statement Report, and accounting code is set for Company Billed card account, the card's accounting code as specified in the Account Code field when creating or editing a CBS account. Maximum length 48 characters. |
amount |
Number |
Maximum 23 digits to the left of the decimal; maximum 8 digits to the right of the decimal; with a maximum of 23 digits for the entire field. | Currency. Value, as credit or debit, of the amount to be exchanged between the payer and payee for this expense account code (not an absolute value) EXAMPLES: Value of zero, credit, or debit, as the following: 0 (Zero) "0," + (Plus / Debit) "+50.00," or - (Minus / Credit) "-50.00." |
debitOrCredit |
String |
DR/CR | Alphanumeric. Either: DR = Debit or CR = credit. |
payee |
String |
- | Alphanumeric. Either a company or an employee depending on the payment type. Maximum length 64 characters. |
payer |
String |
- | Alphanumeric. Either a company or an employee depending on the payment type. Maximum length 64 characters. |
paymentCode |
String |
- | Alphanumeric. The payment code for either a payee or payer. Maximum length 80 characters. |
Insights
Latest Bookings
Gets the latest hotel and air booking for a particular user.
Version
3.0
Retrieve the latest hotel and air booking for a particular user
GET /api/v3.0/insights/latestbookings/
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
user |
string |
query |
The login ID of the user. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter. |
Latest Bookings - Schema
Latest Booking
| Name | Type | Format | Description |
|---|---|---|---|
Airlines |
array |
Airline | The latest booked airline segments. |
Hotel |
Hotel |
- | The latest booked hotel segment. |
Airline
| Name | Type | Format | Description |
|---|---|---|---|
BookingClass |
string |
- | The booking class of the latest booked airline segment. |
Code |
string |
- | The airline code of the latest booked airline segment. |
Hotel
| Name | Type | Format | Description |
|---|---|---|---|
Location |
string |
- | The IATA airport code of the location of the latest booked hotel segment. |
StarRating |
Int32 |
- | The star rating of the latest booked hotel segment. Possible values are from 0 - 5. Values 1 - 5 are mapped to the Northstar standard. If the value is 0, the star rating could not be found. |
Opportunities
Retrieves a collection of opportunities for a specified trip or for all trips that fall within a date range.
- Retrieve a collection of opportunities for a specified trip or for all trips that fall within a date range
- Schema
Version
3.0
Retrieve connection requests that match the TripLink supplier ID
GET https://www.concursolutions.com/api/v3.0/insights/opportunities
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
tripId |
string |
query |
The trip id |
opportunityType |
string |
query |
Comma seperated list of opportunities (Hotel, Car, Air, Rail, Taxi and Service) to get. Do not specify any values to get all opportunities |
fromUtc |
DateTime |
query |
The From date in UTC for the date range |
toUtc |
DateTime |
query |
The To date in UTC for the date range |
Opportunities - Schema
Opportunities
| Name | Type | Format | Description |
|---|---|---|---|
Items |
Array |
Opportunity | The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
Opportunity
| Name | Type | Format | Description |
|---|---|---|---|
EndCityCode |
string |
- | The city code of the destination city where the opportunity is offered |
EndDateLocal |
DateTime |
- | The local end date of the location where the opportunity is offered |
EndPostalCode |
string |
- | The postal code of the destination location where the opportunity is offered |
ID |
string |
- | The unique identifier of the resource. |
IsActive |
boolean |
- | Indicates that the opportunity is currently active |
StartCityCode |
string |
- | The city code of the originating city where the opportunity is offered |
StartDateLocal |
DateTime |
- | The local start date of the location where the opportunity is offered |
StartPostalCode |
string |
- | The postal code of the originating location where the opportunity is offered |
TripId |
string |
- | The trip id of the associated itinerary |
Type |
string |
- | The type of opportunity. Possible values: 'Hotel', 'Car', 'Air', 'Rail', 'Taxi' or 'Service' |
URI |
string |
- | The URI to the resource. |
Invoice
Retrieve Invoice Digests v3
- Retrieves All Invoice Digests Based On the Search Criteria
- Retrieves an Invoice Digest Based On ID
- Schema
Version
3.0
Retrieves All Invoice Digests Based On the Search Criteria
GET /api/v3.0/invoice/paymentrequestdigests
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
offset |
string |
query |
The start of the page offset. |
limit |
Int32 |
query |
The number of records to return. Default: 1,000 |
approvalStatus |
string |
query |
A code representing an Invoice Approval Status. Use GET /invoice/localizeddata to get the available approval status codes. |
paymentStatus |
string |
query |
A code representing an Invoice Payment Status. Use GET /invoice/localizeddata to get the available payment status codes |
vendorInvoiceNumber |
string |
query |
Vendor invoice number tied to the invoice. |
createDateBefore |
DateTime |
YYYY-MM-DD |
The invoice create date is before this date. |
createDateAfter |
DateTime |
YYYY-MM-DD |
The invoice create date is after this date. |
userDefinedDateBefore |
DateTime |
YYYY-MM-DD |
The invoice user defined date is before this date. |
userDefinedDateAfter |
DateTime |
YYYY-MM-DD |
The invoice user defined date is after this date. |
submitDateBefore |
DateTime |
YYYY-MM-DD |
The invoice submit date is before this date. |
submitDateAfter |
DateTime |
YYYY-MM-DD |
The invoice submit date is after this date. |
paidDateBefore |
DateTime |
YYYY-MM-DD |
The invoice paid date is before this date. |
paidDateAfter |
DateTime |
YYYY-MM-DD |
The invoice paid date is after this date. |
payMethodType |
string |
query |
Payment method type tied to an Invoice. Use GET /invoice/localizeddata to get the available Pay Method types. |
lastModifiedDateBefore |
DateTime |
YYYY-MM-DD |
The invoice last modified date is before this date. |
lastModifiedDateAfter |
DateTime |
YYYY-MM-DD |
The invoice last modified date is after this date. |
extractedDateBefore |
DateTime |
YYYY-MM-DD |
The invoice extracted date is before this date. |
extractedDateAfter |
DateTime |
YYYY-MM-DD |
The invoice extracted date is after this date. |
Retrieves an Invoice Digest Based On ID
GET /api/v3.0/invoice/paymentrequestdigests/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The invoice ID |
Retrieve Invoice Digests v3 - Schema
Payment Request Digests
| Name | Type | Format | Description |
|---|---|---|---|
Items |
Array |
Payment Request Digest | The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
PaymentRequestDigest |
Array |
Payment Request Digest | - |
TotalCount |
Int32 |
- | - |
Payment Request Digest
| Name | Type | Format | Description |
|---|---|---|---|
ApprovalStatusCode |
string |
- | Required A code indicating the invoice's approval status. |
CreateDate |
string |
- | The date the invoice was created. |
CurrencyCode |
string |
- | The 3-letter ISO 4217 currency code for the invoice currency. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona. |
ID |
string |
- | The unique identifier of the resource. |
InvoiceNumber |
string |
- | The invoice number of the Invoice. |
IsDeleted |
boolean |
- | A true/false value which indicates whether the invoice has been deleted. (Deleted invoices are retained in the system for historical purposes.). |
OwnerLoginID |
string |
- | The login ID of the Invoice owner. |
OwnerName |
string |
- | The name of the Invoice owner. |
PaidDate |
string |
- | The date when all journal entries in the invoice were integrated with or extracted to the financial system. |
PaymentRequestId |
string |
- | Required The unique identifier of the Invoice summarized in this digest. |
PaymentRequestUri |
string |
- | Required URI of the Invoice summarized in this digest. |
PaymentStatusCode |
string |
- | Required A code indicating the invoice's payment status. |
Total |
string |
- | The total amount of the invoice. |
URI |
string |
- | The URI to the resource. |
UserDefinedDate |
string |
- | The invoice date as assigned by the user. |
VendorName |
string |
- | Required The name of the vendor. |
PaymentMethod |
string |
- | Payment method type tied to an Invoice. |
LastModifiedDate |
string |
- | The date the invoice was last modified. |
ExtractedDate |
string |
- | The date the invoice was extracted. |
Invoice v3
Version
3.0
Retrieve an Invoice
GET /api/v3.0/invoice/paymentrequest/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
| id | string |
path | Required Invoice ID. |
Create a New Invoice
POST /api/v3.0/invoice/paymentrequest
Payload
Update an Invoice
PUT /api/v3.0/invoice/paymentrequest
Payload
Invoice v3 - Schema
Payment Request
| Name | Type | Format | Description |
|---|---|---|---|
AmountWithoutVat |
string |
- | The net amount of the invoice (excluding VAT). |
BuyerCostCenter |
string |
- | The company defined center responsible for the Invoice. |
CheckNumber |
string |
- | Check number of the payment made to the vendor. |
CompanyBillToAddressCode |
string |
- | The code which identifies the company location to which the vendor billed the invoice. |
CompanyShipToAddressCode |
string |
- | The code which identifies the company location to which the vendor shipped items listed in the invoice. |
CountryCode |
string |
- | Required The country code. |
CurrencyCode |
string |
- | The 3-letter ISO 4217 currency code for the invoice currency. Examples: USD - US dollars; BRL - Brazilian real; CAD - Canadian dollar; CHF - Swiss franc; EUR - Euro; GBO - Pound sterling; HKD - Hong Kong dollar; INR - Indian rupee; MXN - Mexican peso; NOK - Norwegian krone; SEK - Swedish krona. |
Custom1 through Custom9 |
string |
- | The details from the Custom fields. These may not have data, depending on configuration. |
DataSource |
string |
- | A code which indicates the method used to created the Invoice. Use GET /invoice/localizeddata to translate the code into text. |
DeliverySlipNumber |
string |
- | The delivery slip number associated with receiving receipt. |
Description |
string |
- | User entered description of the Invoice. |
DiscountPercentage |
string |
- | The discount from the supplier if the discount terms are met. |
DiscountTerms |
string |
- | The NET discount terms with a supplier when discounts apply. |
EmployeeEmailAddress |
string |
- | The email address of the employee to whom the invoice should be assigned. Not evaluated if EmployeeLoginId or EmployeeId match an employee. This value is required if none of the following are provided: LedgerCode; EmployeeLoginId, EmployeeId; PurchaseOrderNumber; ExternalPolicyId. |
EmployeeId |
string |
- | The company ID of the employee to whom the invoice should be assigned. Has precedence over EmployeeEmail; not evaluated if EmployeeLoginId matches an employee. This value is required if none of the following are provided: LedgerCode; EmployeeLoginId; EmployeeEmail; PurchaseOrderNumber; ExternalPolicyId. |
EmployeeLoginId |
string |
- | The login ID of the employee to whom the invoice should be assigned. Has precedence over EmployeeId and EmployeeEmail. This value is required if none of the following are provided: LedgerCode; EmployeeId; EmployeeEmail; PurchaseOrderNumber; ExternalPolicyId. |
ExternalPolicyId |
string |
- | The external policy ID of the Invoice. This value is required if none of the following are provided: LedgerCode; EmployeeLoginId, EmployeeId; EmployeeEmail; PurchaseOrderNumber. |
InvoiceAmount |
string |
- | Required User-entered value representing the total invoice amount, used to calculate amount remaining on the line item page. |
InvoiceDate |
string |
- | The date the vendor issued the Invoice. |
InvoiceNumber |
string |
- | The Invoice Number from the vendor for the Invoice. |
InvoiceReceivedDate |
string |
- | The date on which the invoice was received. |
IsEmergencyCheckRun |
string |
- | Is an emergency check run required (Y/N). |
IsInvoiceConfirmed |
boolean |
- | Indicates if the Invoice is confirmed or in a different status Supported values: true, false |
LedgerCode |
string |
- | A code which indicates which company journal the Invoice is assigned to. Use GET /invoice/localizeddata to obtain valid codes. This value is required if none of the following are provided: EmployeeLoginId; EmployeeId; EmployeeEmail; PurchaseOrderNumber; ExternalPolicyId. |
LineItems |
array |
LineItem |
The details of the Core Payment Request Line Item Identity Fields. |
Name |
string |
- | Required The Invoice name. |
NotesToVendor |
string |
- | Information from the customer to the vendor for special requests or handling for the ordered good or service. |
OB10BuyerId |
string |
- | A unique buyer account on the OB10 network. |
OB10TransactionId |
string |
- | Unique Identifier for the Invoice transaction (generated by OB10). |
OrgUnit1 |
string |
- | The details from the Organization Unit fields. These may not have data, depending on configuration. |
OrgUnit2 |
string |
- | The details from the Organization Unit fields. These may not have data, depending on configuration. |
OrgUnit3 |
string |
- | The details from the Organization Unit fields. These may not have data, depending on configuration. |
OrgUnit4 |
string |
- | The details from the Organization Unit fields. These may not have data, depending on configuration. |
OrgUnit5 |
string |
- | The details from the Organization Unit fields. These may not have data, depending on configuration. |
OrgUnit6 |
string |
- | The details from the Organization Unit fields. These may not have data, depending on configuration. |
PaymentAdjustmentNotes |
string |
- | Notes to the vendor regarding the amount paid (underpayment due to damages, for example). |
PaymentAmount |
string |
- | Represents the amount of the payment that will be/has been made for the Invoice. |
PaymentDueDate |
string |
- | The date the vendor needs to be paid by. |
PaymentTermsDays |
string |
- | This number, along with type of payment terms (example: NET), determine when the invoice is expected to be paid. |
ProvincialTaxId |
string |
- | The Vendor Provincial Tax ID. |
PurchaseOrderId |
string |
- | The ID of the Purchase Order to which the Invoice should be matched. This value is required if none of the following are provided: LedgerCode; EmployeeLoginId, EmployeeId, EmployeeEmail, ExternalPolicyId. |
ReceiptConfirmationType |
string |
- | A code which indicates the receipt confirmation type for this Invoice (Invoice Confirmation, for example). Use GET /invoice/localizeddata to translate the code into text. |
ShippingAmount |
string |
- | The value for the Shipping Amount header field. |
TaxAmount |
string |
- | The value for the Tax Amount header field. |
VatAmountOne |
string |
- | The amount of VAT included in the invoice total (first of two VAT amount fields available). |
VatAmountTwo |
string |
- | The amount of VAT included in the invoice total (second of two VAT amount fields available). |
VatRateOne |
string |
- | The VAT rate applied to the net invoice total (should relate to the first VAT amount field). |
VatRateTwo |
string |
- | The VAT rate applied to the net invoice total (should relate to the second VAT amount field). |
VendorRemitToIdentifier |
object |
VendorRemitToIdentifier |
Required Used to identify the vendor location for payment remittance. At a minimum, the VendorCode or the combination of (VendorName, Address1, and PostalCode) are required. Use of as many fields as possible is encouraged to ensure a single vendor can be identified. If more than one vendor matches the information provided, the Invoice creation attempt will fail. |
VendorShipFromAddressCode |
string |
- | The code which identifies the location from which the vendor shipped items listed in the invoice. |
VendorTaxId |
string |
- | The Vendor Tax ID. |
LineItem
| Name | Type | Format | Description |
|---|---|---|---|
Allocations |
array |
Allocation |
The details of the Invoice allocation fields. |
AmountWithoutVat |
string |
- | The net amount of the line item (excluding VAT). |
Custom1 through Custom20 |
string |
- | The details from the Custom fields. These may not have data, depending on configuration. |
Description |
string |
- | Brief overview of the good or service ordered. |
ExpenseTypeCode |
string |
- | A code which indicates the Expense Type for the Line Item. |
ItemCode |
string |
- | Represents the item code (the unique code a vendor assigns to a good or code a vendor assigns to a good or service to identify it). |
MatchedPurchaseOrderReceipts |
array |
MatchedPurchaseOrderReceipt |
The details of the Matched Purchase Order Receipts Identity Fields (if any). |
PurchaseOrderNumber |
string |
- | Purchase Order that is associated to the Line Item . |
Quantity |
string |
- | Total number of goods or services ordered. |
ShipFromPostalCode |
string |
- | The postal code the good or service was shipped from. |
ShipToPostalCode |
string |
- | The postal code the good or service will be shipped to. |
SupplierPartId |
string |
- | The unique identifier provided by the supplier that is associated with the good or service. |
Tax |
string |
- | The tax associated with the line item. |
TotalPrice |
string |
- | The total amount of the line item. |
UnitOfMeasure |
string |
- | The code for the measurement unit used to quantify the good or service. Use GET /invoice/localizeddata to look up codes and descriptions. |
UnitPrice |
string |
- | The cost for a single unit of the line item good or service. |
VatAmount |
string |
- | The amount of VAT included in the line item total. |
VatRate |
string |
- | The VAT rate applied to the net line item total. |
Allocation
| Name | Type | Format | Description |
|---|---|---|---|
Custom1 through Custom7 |
string |
- | The details from the Custom fields. These may not have data, depending on configuration. |
Custom8 |
string |
- | A value that can be applied to a custom field 8 that is part of the allocation form. |
Custom9 |
string |
- | A value that can be applied to a custom field 9 that is part of the allocation form. |
Custom10 |
string |
- | A value that can be applied to a custom field 10 that is part of the allocation form. |
Custom11 through Custom20 |
string |
- | The details from the Custom fields. These may not have data, depending on configuration. |
Percentage |
string |
- | Required The percentage of the Request Line Item that the individual allocation record. All Allocations associated to a given Line Item should add up to 100. |
MatchedPurchaseOrderReceipt
| Name | Type | Format | Description |
|---|---|---|---|
GoodsReceiptNumber |
string |
- | The identifier of the purchase order goods receipt number to which the Invoice line item is matched. |
VendorRemitToIdentifier
| Name | Type | Format | Description |
|---|---|---|---|
Address1 |
string |
- | Line 1 of the street address. |
AddressCode |
string |
- | The code which identifies a particular vendor location. |
Name |
string |
- | The name of the vendor. |
PostalCode |
string |
- | The postal / zip code. |
VendorCode |
string |
- | The code which identifies a particular vendor. |
Invoice Pay v4
- Overview
- Process Flow
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Obtaining Payments
- Updating a Payment With Status
- Schema
- Definitions
Invoice Pay v4 - Overview
SAP Concur partners with external payment providers for processing invoice payments. These payment providers are listed on the App Center and can integrate with the Invoice product by using the Invoice Pay APIs. Payment providers can get a list of all the payments authorized to be processed by them, and send back status of those payments.
Limitations: This API is only available for use by payment partners who will be processing invoice payments. This API can accept a maximum of 1,000 requests per minute across all payment providers. This API is available only in the North America Data Center.
Invoice Pay v4 - Process Flow

Invoice Pay v4 - Products and Editions
- Concur Invoice Professional Edition
- Concur Invoice Standard Edition
Invoice Pay v4 - Scope Usage
| Name | Description | Endpoint |
|---|---|---|
invoice.providerpayment.write |
Read access to pending payments, and write access to payment status | GET,POST |
Invoice Pay v4 - Dependencies
This API can only be used with SAP Concur clients who have purchased Concur Invoice.
Invoice Pay v4 - Access Token Usage
This API supports only Company access tokens.
Invoice Pay v4 - Obtaining payments
Payment providers can use this endpoint to get a list of payments.
* This method will return all payments with a status PENDING_RETRIEVAL and payment method PAVPVD. After an invoice is approved and extracted it will be converted into a payment with status PENDING_RETRIEVAL.
* It returns a maximum of 500 records at a time. In order to ensure that all payments are retrieved, call this method until you receive an empty payment in the response.
* The payment provider will need to acknowledge that payments were received, using Updating a Payment With Status and updating the status of the payment to any status other than PENDING_RETRIEVAL.
Request
URI
Template
GET https://us.api.concursolutions.com/invoice/provider-payment/v4/payments
Headers
Payload
None.
Response
Status Codes
Headers
- RFC 7231 Content-Type
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Example
Request
GET https://us.api.concursolutions.com/invoice/provider-payment/v4/payments
Accept: application/json
Authorization: BEARER {token}
Response
200 OK
Content-Type: application/json
{
"payments": [
{
"paymentId": "0f27533f-ce38-4f43-a2f3-fa9f0e6b33fc",
"paymentMethod": "PAYPVD",
"paymentDueDate": "2018-08-09",
"totalAmount":{
"amount": "30.00",
"currency": "USD"
},
"invoices": [
{
"invoiceNumber": "AGH87",
"invoiceID": "1ADFBB440D7045F68DE2",
"invoiceAmount":{
"amount": "30.00",
"currency": "USD"
},
"paymentAmount":{
"amount": "30.00",
"currency": "USD"
},
"notesToSupplier": null
}
],
"vendor":{
"addressLine1": "1234 Rain Street",
"addressLine2": null,
"addressLine3": null,
"vendorAddrCode": "1160",
"city": "Chicago",
"state": "IL",
"postalCode": "60680-28160",
"countryName": "UNITED STATES",
"countryCode": "US",
"firstName": "Terry",
"lastName": "Brown",
"phoneNumber": null,
"email": "terry.brown@example.com",
"vendorCode": "1160",
"vendorName": "Dell",
"buyerAccountNumber": "1234567890"
}
}
]
}
Updating a Payment With Status
Payment providers can use this endpoint to provide updates to the status of payments.
Request
URI
Template
POST https://us.api.concursolutions.com/invoice/provider-payment/v4/payments/{paymentId}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
paymentId |
string |
- | Required The identifier of the payment to update. |
Headers
Payload
Response
Status Codes
Headers
concur-correlationidis a SAP Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Content-Type
Payload
Example
Request
POST https://us.api.concursolutions.com/invoice/provider-payment/v4/payments/0f27533f-ce38-4f43-a2f3-fa9f0e6b33fc
Authorization: BEARER {token}
Content-Type: application/json
{
"providerReference" : "hdoesofdl",
"status" : "PAID",
"statusMessage" : "Payment was successful",
"paymentAdjustmentNotes" : null,
"statusDate" : "2018-05-10",
"paymentInitiationDate" : "2018-05-09",
"paymentSettlementDate" : "2018-05-09",
"thirdPartyPaymentIdentifier" : "69249",
"paymentMethod" : "CHECK",
"paidAmount" : {
"amount": "30.00",
"currency": "USD"
}
}
Response
200 OK
Content-Type: application/json
{
"createdDate" : "2018-05-09",
"lastModifiedDate" : "2018-05-09",
"status" : "PAID",
"statusMessage" : "Payment was successful",
"paymentAdjustmentNotes" : null,
"statusDate" : "2018-05-10",
"paymentInitiationDate" : "2018-05-09",
"paymentSettlementDate" : "2018-05-09",
"thirdPartyPaymentIdentifier" : "69249",
"paymentMethod" : "CHECK",
"paidAmount" : {
"amount": "30.00",
"currency": "USD"
}
}
Invoice Pay v4 - Schema
Payments
| Name | Type | Format | Description |
|---|---|---|---|
payments |
array |
Payment | Array of payments. |
Payment
| Name | Type | Format | Description |
|---|---|---|---|
invoices |
array |
Invoice | Array of invoices that need to be batched in a payment. |
paymentDueDate |
string |
YYYY-MM-DD | The date by which the payment should be made. |
paymentID |
string |
- | Unique identifier of the payment in SAP Concur. Maximum 36 characters. |
paymentMethod |
string |
- | The value is always PAYPVD which means that the client wants to pay using a payment provider. Maximum 15 characters. |
totalAmount |
object |
Amount | This amount needs to be paid to the vendor. |
vendor |
object |
Vendor | Vendor requesting the payment. |
Invoice
| Name | Type | Format | Description |
|---|---|---|---|
invoiceAmount |
object |
Amount | Amount on the invoice. |
invoiceNumber |
string |
- | Invoice Number. Maximum 50 characters. |
invoiceId |
string |
- | Unique identifier of the invoice in SAP Concur. This can be used to get additional invoice information from other APIs. This is the same as paymentRequestID in other Invoice APIs. Maximum 20 characters. |
notesToSupplier |
string |
- | Notes to the supplier contain remittance information that the buyer wants to provide to the supplier. Maximum 500 characters. |
paymentAmount |
object |
Amount | Payment amount on the invoice. |
Vendor
| Name | Type | Format | Description |
|---|---|---|---|
buyerAccountNumber |
string |
- | Buyer Account Number. Maximum 50 characters. |
vendorCode |
string |
- | Vendor Code. Maximum 32 characters. |
vendorName |
string |
- | Vendor Name. Maximum 255 characters. |
addressLine1 |
string |
- | Vendor Address line 1. Maximum 255 characters. |
addressLine2 |
string |
- | Vendor Address line 2. Maximum 255 characters. |
addressLine3 |
string |
- | Vendor Address line 3. Maximum 255 characters. |
city |
string |
- | Vendor Address City. Maximum 255 characters. |
state |
string |
- | Vendor Address State. Maximum 10 characters. |
countryCode |
string |
- | Vendor Address Country Code. Maximum 2 characters. |
countryName |
string |
- | Vendor Address Country Name. Maximum 64 characters. |
postalCode |
string |
- | Vendor Address Postal Code. Maximum 20 characters. |
vendorAddrCode |
string |
- | Vendor Address Code. Maximum 64 characters. |
email |
string |
- | Email Address. Maximum 255 characters. |
firstName |
string |
- | First Name. Maximum 255 characters. |
lastName |
string |
- | Last Name. Maximum 255 characters. |
phoneNumber |
string |
- | Phone Number. Maximum 25 characters. |
Amount
| Name | Type | Format | Description |
|---|---|---|---|
amount |
string |
- | Amount. Maximum 20 characters. |
currency |
string |
- | Currency Code. Maximum 3 characters. |
Payment Update
| Name | Type | Format | Description |
|---|---|---|---|
providerReference |
string |
- | Unique identifier of the payment in the payment provider's system. This will be used for internal troubleshooting. Maximum 100 characters. |
status |
string |
Payment Update Status | Required Used to depict success, error or any other intermediate state, defined by SAP Concur. |
statusMessage |
string |
- | Payment provider description of the status. Providers can supply any message. Maximum 255 characters. |
paymentAdjustmentNotes |
string |
- | Payment adjustment notes sent by the payment provider. Maximum 255 characters. |
statusDate |
string |
YYYY-MM-DD | Required The date that the payment provider recorded this status change. |
paymentInitiationDate |
string |
YYYY-MM-DD | The date the payment was initiated. |
paymentSettlementDate |
string |
YYYY-MM-DD | The date the payment will be in the payees account. |
thirdPartyPaymentIdentifier |
string |
- | Check number if the payment was done via check or trace number for ACH payments. Maximum 255 characters. |
paymentMethod |
string |
Payment Provider Method | Required if the status is PAID, CHECK_PROCESSED, or CARD_SETTLED Payment method used by the payment provider. |
paidAmount |
object |
Amount | Required if the status is PAID, CHECK_PROCESSED, or CARD_SETTLED Amount paid by the payment provider. |
Payment Update Result
| Name | Type | Format | Description |
|---|---|---|---|
createdDate |
string |
YYYY-MM-DD | The date the payment was created. |
lastModifiedDate |
string |
YYYY-MM-DD | The date the payment was last modified. |
providerReference |
string |
- | Unique identifier of the payment in the payment provider's system. Maximum 100 characters. |
status |
string |
Payment Update Status | Required Used to depict success, error or any other intermediate state, defined by SAP Concur. |
statusMessage |
string |
- | Payment provider description of the status. Providers can supply any message. Maximum 255 characters. |
paymentAdjustmentNotes |
string |
- | Payment adjustment notes sent by the payment provider. Maximum 255 characters. |
statusDate |
string |
YYYY-MM-DD | Required The date that the payment provider recorded this status change. |
paymentInitiationDate |
string |
YYYY-MM-DD | The date the payment was initiated. |
paymentSettlementDate |
string |
YYYY-MM-DD | The date the payment will be in the payees account. |
thirdPartyPaymentIdentifier |
string |
- | Check number if the payment was done via check or trace number for ACH payments. Maximum 255 characters. |
paymentMethod |
string |
Payment Provider Method | Required if the status is PAID, CHECK_PROCESSED, or CARD_SETTLED Payment method used by the payment provider. |
paidAmount |
object |
Amount | Required if the status is PAID, CHECK_PROCESSED, or CARD_SETTLED Amount paid by the payment provider. |
Errors
| Name | Type | Format | Description |
|---|---|---|---|
errors |
array |
Error | An array of errors. |
Error
| Name | Type | Format | Description |
|---|---|---|---|
errorCode |
string |
- | Required Machine readable code associated with the error. |
errorMessage |
string |
- | Required Human readable message associated with the error. |
Invoice Pay v4 - Definitions
Payment Update Status
| Value | Description | Status available in the Payment Confirmation Extract |
|---|---|---|
PENDING_RETRIEVAL |
Not yet retrieved by the payment provider | Not available |
RETRIEVED |
Retrieved by the payment provider | Not available |
PROCESSING |
Payment is being processed by the payment provider | Not available |
REJECTED |
Payment was rejected by the payment provider | Not available |
RETURNED |
Payment was returned by the bank | Not available |
CANCELED |
Payment was canceled | FAILED |
CHECK_PRINTED |
Check was printed | Not available |
CHECK_MAILED |
Check was mailed | Not available |
CHECK_PROCESSED |
Check was processed | PAID |
CHECK_VOIDED |
Check was voided | VOID |
PAID |
Payment was successfully made | PAID |
CARD_EMAIL_SENT |
Email with card information sent to vendor | Not available |
CARD_AUTHORIZED |
Card was authorized by the merchant | Not available |
CARD_SETTLED |
Card was settled by vendor | PAID |
Payment Provider Method
| Value | Description |
|---|---|
ACH |
ACH payment |
CHECK |
Check payment |
WIRE |
Wire payment |
CARD |
Virtual Card payment |
OTHER |
Any other payment method |
Purchase Orders v3
The Purchase Orders API gives SAP Concur clients the ability to leverage external data to create and update approved purchase orders. Clients can build a direct connection to the Purchase Orders API which will create purchase orders for invoices to be associated to. It also allows clients to update created purchase orders when orders change, need to be closed, or identify and resolve matching exceptions on PO invoices.
Limitations: This API is not available in the China Data center. This API is only available for direct integrations with an existing SAP Concur client. This API can only be used to create new purchase requests and get the details of the created purchase request. This API cannot update, edit, or delete purchase requests. All edits or processing of the purchase request after it is sent to SAP Concur and created must be done in SAP Concur.
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Create a New Purchase Order
- Update Purchase Order Line Item with Receipt Information
- Update an Existing Purchase Order
- Get an Existing Purchase Order
- Schema
- Response Schema
- Receipt Schema
- Error Codes
Purchase Orders v3 - Products and Editions
- Concur Invoice Professional Edition
- Concur Invoice Standard Edition
Purchase Orders v3 - Scope Usage
Required Scopes:
| Name | Description | Endpoint |
|---|---|---|
INVPO |
Create, update, and retrieve purchase orders. | POST, PUT, GET |
Purchase Orders v3 - Dependencies
SAP Concur clients must purchase Concur Invoice, Concur Purchase Order, and Concur Web Services in order to use this API. Concur Invoice with Concur Purchase Order must be configured before using this API.
To create purchase orders, you need to supply a Vendor Code and Vendor Address Code. You can access Vendor Manager in Concur Invoice to see these values. If you need to get this data from SAP Concur using web services, you can use the Vendor v3 API.
If your purchase order form in SAP Concur has required custom fields that are tied to lists, you will need to supply the Item Code for the list items. You can access List Management in SAP Concur to see your list items and list item codes. If you need to get this data from SAP Concur using web services, you can use the List Item v3 API to retrieve the Level1Code value for the list items.
Purchase Orders v3 - Access Token Usage
This API will work with both company or user access tokens. A company access token is required if the integration will create purchase orders for multiple requestors. Using a user access token to create purchase order results in the purchase order being assigned to the user that generated the user access token, not the user set in the payload. A user access token can be used for testing purposes.
Create a New Purchase Order
POST /api/v3.0/invoice/purchaseorders
Create or update a Purchase Order. Batch processing is not available using the Purchase Order API. Please use Import Jobs for batch updates.
Payload
Example
{
"BillToAddress": {
"Address1": "add1",
"Address2": "add2",
"Address3": "add3",
"City": "city",
"CountryCode": "US",
"ExternalID": "billtoapi",
"Name": "billto",
"PostalCode": "55426",
"StateProvince": "MN"
},
"CurrencyCode": "USD",
"OrderDate":"2011-08-12T20:17:46.384Z",
"ID": "API101",
"IsTest": "false",
"IsChangeOrder": "false",
"LedgerCode": "23",
"LineItem": [
{
"Allocation": [
{
"Amount": "106.74",
"Percentage":"100.00000000",
"GrossAmount":"106.74"
}
],
"CreateDate": "2019-12-13 20:00:37.0",
"Description": "line 1",
"ExpenseType": "Advertising",
"ExternalID": "API100line1",
"IsReceiptRequired": "true",
"LineNumber": "1",
"PurchaseOrderReceiptType": "WQTY",
"Quantity": "1.00",
"UnitOfMeasureCode":"DA",
"UnitPrice": "106.74"
}
],
"Name": "poName",
"PolicyExternalID": "PO",
"PurchaseOrderNumber": "API101",
"PurchaseRequestNumber": "100001",
"RequestedBy": "Deo, John",
"Shipping": "0.00000000",
"ShipToAddress": {
"Address1": "add1",
"Address2": "add2",
"Address3": "add3",
"City": "cityship",
"CountryCode": "US",
"ExternalID": "Shiptoapi",
"Name": "shiptoapi",
"PostalCode": "55426",
"StateProvince": "MN"
},
"Status": "Transmitted",
"Tax": "0.00000000",
"URI": "http://www.concursolutions.com/api/v3.0/invoice/purchaseorders/purchaseorders/API101",
"VendorCode": "VEN1",
"VendorAddressCode": "VEN1ADDR1"
}
Response
Update Purchase Order Line Item With Receipt Information
PUT /api/v3.0/invoice/purchaseorderreceipts
Payload
Response
Purchase Orders v3 - Update an Existing Purchase Order
PUT /api/v3.0/invoice/purchaseorders
Payload
Response
Purchase Orders v3 - Get an Existing Purchase Order
GET /api/v3.0/invoice/purchaseorders/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
{id} | The identifier for the purchase order. |
Input
None
Response
Purchase Orders v3 - Schema
purchaseOrder
| Name | Type | Format | Description |
|---|---|---|---|
AmountWithoutVat |
string |
- | The net amount of the purchase order (excluding VAT). |
BillToAddress |
object |
BillToAddress |
Required The customer's billing address, which is where the vendor should send the bill. |
CurrencyCode |
string |
- | Required The 3-letter ISO 4217 currency code of the currency that is associated with the purchase order. |
Custom1 through Custom24 |
string |
- | A value that can be applied to a custom field that is part of the purchase order header form. |
Description |
string |
- | A description of the purchase order. |
DiscountPercentage |
string |
- | The discount from the vendor, if the discount terms are met. |
DiscountTerms |
string |
- | The net discount terms that the vendor offers, when discounts apply. |
ID |
string |
- | The unique identifier of the resource. |
IsTest |
string |
true / false |
If the purchase order is a test. |
IsChangeOrder |
string |
true / false |
If the purchase order has a change order or not. |
LedgerCode |
string |
- | A code which indicates which company journal the Purchase Order is assigned to. |
LineItem |
array |
LineItem |
Required The line items in a purchase order. |
Name |
string |
- | Required A name for the purchase order. |
NeededByDate |
string |
YYYY-MM-DD |
The date by which the purchase order must be fulfilled. |
OrderDate |
string |
YYYY-MM-DD |
Required The date when goods were ordered. |
PaymentTerms |
string |
- | The net payment terms that have been set up with a vendor. |
PolicyExternalID |
string |
- | Required The external identifier of the policy that should be associated with the purchase order. The external Id is a property of the policy configuration screen. Clients will need to get these ID’s from the Implementation team if using professional version. For standard version the value is always PO. |
PoVendorTaxId |
string |
- | The vendor tax ID. |
ProvincialTaxId |
string |
- | The vendor provincial tax ID. |
PurchaseOrderNumber |
string |
- | The purchase order number. |
PurchaseRequestNumber |
string |
- | The related purchase request number that generated the purchase order. |
ReceiptType |
string |
- | The purchase order receipt type (Deprecated). Use the PurchaseOrderReceiptType at line item level instead. |
RequestedBy |
string |
- | The person who requests the goods in the purchase order. |
RequestedDeliveryDate |
string |
YYYY-MM-DD |
The date the purchase order instructed the vendor to deliver the goods. |
Shipping |
string |
- | The total shipping cost for the purchase order. |
ShippingDescription |
string |
- | A description of how the goods in the purchase order will ship. For example, via FedEx. |
ShippingMethodKey |
string |
- | A code that represents the shipping method used by the vendor. Maximum length: 10 characters |
ShippingTermsKey |
string |
- | A code that represents the shipping terms that the vendor offers. Maximum length: 10 characters |
ShipToAddress |
object |
ShipToAddress |
Required The customer's shipping address, which is where the vendor should ship the goods. |
Status |
string |
- | The current status of the purchase order. Default: Transmitted. Supported values: Closed, Transmitted |
Tax |
string |
- | The total tax for the purchase order. |
URI |
string |
- | The URI to the resource. |
VatAmountOne |
string |
- | This field has not been implemented by Purchase Request yet. Any data in this field will be ignored. |
VatAmountTwo |
string |
- | This field has not been implemented by Purchase Request yet. Any data in this field will be ignored. |
VatRateOne |
string |
- | This field has not been implemented by Purchase Request yet. Any data in this field will be ignored. |
VatRateTwo |
string |
- | This field has not been implemented by Purchase Request yet. Any data in this field will be ignored. |
VendorAccountNumber |
string |
- | The vendor account number. |
VendorAddressCode |
string |
- | Required The code that identifies the vendor's remit address for the purchase order. |
VendorCode |
string |
- | Required The code that identifies the vendor for the purchase order. |
BillToAddress
| Name | Type | Format | Description |
|---|---|---|---|
Address1 |
string |
- | Required Address line 1 of the billing address. |
Address2 |
string |
- | Address line 2 of the billing address. |
Address3 |
string |
- | Address line 3 of the billing address. |
City |
string |
- | Required The city of the billing address. |
CountryCode |
string |
- | Required The code of the country for the billing address. |
ExternalID |
string |
- | Required A unique value supplied by the customer to identify a particular billing address. |
Name |
string |
- | An optional name that can be given to the billing address. |
PostalCode |
string |
- | Required The postal code of the billing address. |
StateProvince |
string |
- | Required The state or province of the billing address. |
LineItem
| Name | Type | Format | Description |
|---|---|---|---|
AccountCode |
string |
- | The account code of the line item. A value must be supplied for either ExpenseType or AccountCode, but not both. This field is required if an ExpenseType value is not supplied. |
Allocation |
array |
Allocation |
A list of the allocations that are associated with the line item. Allocation elements can be repeated within the same line items to represent multiple allocations. |
AmountWithoutVat |
string |
- | The net amount of the line item (excluding VAT). |
CreateDate |
string |
YYYY-MM-DD |
The date the line item was created. |
Custom1 through Custom20 |
string |
- | A value that can be applied to a custom field 1 that is part of the purchase order line item form. |
Description |
string |
- | A description of the line item. |
ExpenseType |
string |
- | The expense type of the line item. A value must be supplied for either ExpenseType or AccountCode, but not both. This field is required if an AccountCode value is not supplied. |
ExternalID |
string |
- | Required A customer-supplied value that uniquely identifies the line item within the purchase order. |
IsReceiptRequired |
string |
true / false |
Indicates whether the line item requires a receipt. |
LineNumber |
string |
- | Required The line item number within the purchase order. |
Quantity |
string |
- | Required The quantity associated with the line item. |
PurchaseOrderReceiptType |
string |
- | Purchase order ReceiptType of the line item. If you are using Concur Receiving and need to enter Goods Receipts against the resulting PO lines use QUANTITY_RECEIPT. Default: NONE. Supported values: QUANTITY_RECEIPT, NONE |
RequestedBy |
string |
- | The person who requests the goods in the line item of the purchase order. |
RequestedDeliveryDate |
string |
YYYY-MM-DD |
The date the line item of the purchase order instructed the vendor to deliver the goods. |
SupplierPartID |
string |
- | Any number that might help to identify the line item. This could be a value such as the vendor's part number or even the manufacturer number. |
Tax |
string |
- | Any tax that is associated with the line item. |
UnitOfMeasureCode |
string |
- | The unit of measure code of the line item. |
UnitPrice |
string |
- | Required The price of each item of the line item. |
VatAmount |
string |
- | This field has not been implemented by Purchase Request yet. Any data in this field will be ignored. |
VatRate |
string |
- | This field has not been implemented by Purchase Request yet. Any data in this field will be ignored. |
Allocation
| Name | Type | Format | Description |
|---|---|---|---|
Amount |
string |
- | Required The total amount of the allocation. |
Custom1 through Custom20 |
string |
- | A value that can be applied to a custom field 1 that is part of the allocation form. |
GrossAmount |
string |
- | Required The allocation gross amount. |
Percentage |
string |
- | Required The allocation percentage. |
ShipToAddress
| Name | Type | Format | Description |
|---|---|---|---|
Address1 |
string |
- | Required Address line 1 of the shipping address. |
Address2 |
string |
- | Address line 2 of the shipping address. |
Address3 |
string |
- | Address line 3 of the shipping address. |
City |
string |
- | Required The city of the shipping address. |
CountryCode |
string |
- | Required The code of the country for the shipping address. |
ExternalID |
string |
- | Required A unique value supplied by the customer to identify a particular shipping address. |
Name |
string |
- | An optional name that can be given to the shipping address. |
PostalCode |
string |
- | Required The postal code of the shipping address. |
StateProvince |
string |
- | Required The state or province of the shipping address. |
Response Schema
| Name | Type | Format | Description |
|---|---|---|---|
ErrorCode |
string |
- | A code that indicates why the purchase order was not processed successfully. |
ErrorMessage |
string |
- | A description of the error. |
FieldCode |
string |
- | A code that indicates which field caused an issue. This code typically appears only when a field is being validated against a field of a form type. Format: LEVEL CODE. The possible levels are: Header, ShipTo, BillTo, LineItem, Allocation. |
LineItemExternalID |
string |
- | The external ID of a line item that caused an error. If the error is related to an allocation, this field indicates the external ID of the line item that the allocation is associated with, and also indicates the allocation that caused of the error. |
Message |
string |
- | |
PurchaseOrderNumber |
string |
- | The purchase order number. |
Status |
string |
SUCCESS / FAILURE |
The result of processing the purchase order. |
Receipt Schema
| Name | Type | Format | Description |
|---|---|---|---|
IsReceived |
string |
- | Required Indicates whether the line item was received. |
LineItemExternalID |
string |
- | Required A customer-supplied value that uniquely identifies the line item within the purchase order. |
PurchaseOrderNumber |
string |
- | Required The purchase order number. |
ReceivedDate |
string |
YYYY-MM-DD |
The date the line item was received. |
ReceivedQuantity |
string |
- | The number of items that were received. |
Error Codes
The web service will not return a 4xx HTTP response code for a batch operation even when every item in the batch failed to be created, updated or deleted. The client must inspect the response to look for warnings or errors with individual batch items.
| Code | Description |
|---|---|
| 1000 | The PO number is missing or invalid. |
| 2000 | There was no vendor found for the supplied Vendor Code and Vendor Address Code. |
| 3000 | The Currency Code is missing or invalid. |
| 4000 | There was no policy found matching the supplied External Id. |
| 4001 | The policy does not support purchase orders. |
| 4002 | The policy cannot be changed on the purchase order. |
| 5000 | The purchase order does not contain any line items. |
| 5001 | The line item must contain expense type or account code, but not both. |
| 5002 | The line item expense type is invalid. |
| 5003 | The line item account code is invalid. |
| 5004 | The line item tax and unit price must both match positive or negative. |
| 5500 | The line item contains an allocation, but no allocation form is defined. |
| 5501 | The line item allocation amounts exceed the line item total. |
| 5502 | The distribution amounts for a line item must match the line item amount positive or negative. |
| 5503 | The distribution amounts for a line item cannot be zero. |
| 5600 | The external id for the line item is not unique across the purchase order. |
| 6000 | The Ship To Address is missing or invalid. |
| 6001 | The Bill To Address is missing or invalid. |
| 8000 | A required field is missing. |
| 8001 | A field’s value exceeds the maximum length allowed. |
| 8002 | A field’s value is not the correct data type. |
| 8003 | A field’s value is an invalid list item. |
| 8004 | A field’s value is an invalid connected list item. |
| 8005 | The Country Code is missing or invalid. |
| 8006 | A value was supplied for a field that is not part of the form. |
| 9999 | An unexpected error occurred. |
Purchase Request v4 - Get Started
The Purchase Request API gives SAP Concur clients the ability to leverage external data to create purchase requests for pre-authorization of purchase orders. Clients can build a direct connection to the Purchase Request API which will create new purchase requests and automatically submit them into the pre-authorization workflow. Once approved, the purchase request results in a purchase order that can be transmitted to a vendor from SAP Concur.
Use Case
Many Concur Invoice clients have external systems that have part or service lists with pricing. If they use SAP Concur pre-authorization using purchase request, the data from the external systems must be entered manually into the purchase request cart and submitted for approval by the requesting employee. Using this API and a client-built integration, the requestor can browse and select the items from the external system with quantities and other details needed, and then send the data to SAP Concur. A purchase request will be created and submitted into the workflow. The API returns a response message with a record identifier (URI), which can be used with the Get Purchase Request Details method to get the basic details of the created purchase request: Concur Purchase Request number, workflow status, exceptions, and once approved, the resulting SAP Concur purchase order number.
Limitations
This API is not available in the China Data center. This API is only available for direct integrations with an existing SAP Concur client. If you are a Partner looking to build an App Center App using this API, please reach out to your SAP Concur Representative. This API can only be used to create new purchase requests and get the details of the created purchase request. This API cannot update, edit, or delete purchase requests. All edits or processing of the purchase request after it is sent to SAP Concur and created must be done in SAP Concur.
- Regional Availability
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Purchase Request API Endpoints
Purchase Request v4 - Get Started - Regional Availability
https://us.api.concursolutions.com/purchaserequest/v4/
https://emea.api.concursolutions.com/purchaserequest/v4/
Purchase Request v4 - Get Started - Products and Editions
- Concur Invoice Professional Edition
- Concur Invoice Standard Edition
Purchase Request v4 - Get Started - Scope Usage
| Name | Description | Endpoint |
|---|---|---|
| purchaserequest.write | Allows you to create new purchase requests | POST |
| purchaserequest.read | Allows you to retrieve purchase requests | GET |
Purchase Request v4 - Get Started - Dependencies
SAP Concur clients must purchase Concur Invoice, Concur Purchasing, and Concur Web Services in order to use this API. Concur Invoice with Concur Purchasing must be configured before using this API.
To create purchase requests, you need to supply a Vendor Code and Vendor Address Code. You can access Vendor Manager in Concur Invoice to see these values. If you need to get this data from SAP Concur using web services, you can use the Vendor v3 API.
If your purchase request form in SAP Concur has required custom fields that are tied to lists, you will need to supply the Item Code for the list items, or configure them to copy down from another source such as Employee. You can access List Management in SAP Concur to see your list items and list item codes. If you need to get this data from SAP Concur using web services, you can use the List Item v3 API to retrieve the Level1Code value for the list items.
Purchase Request v4 - Get Started - Access Token Usage
This API will work with both Company or User access tokens, however a Company access token is required if the integration will create purchase requests for multiple requestors. Using a User access token to create purchase requests results in the purchase request being assigned to the user that generated the User access token, not the user set in the payload. A User access token can be used for testing purposes.
Retrieve a Company Access Token
Clients connecting to this API to build a custom integration will receive client credentials and information on how to generate your Company access token or Company refresh token from your Concur Technical Enablement resource.
Retrieve a User Access Token
This API supports User access tokens, however any purchase requests created using a User access token will only create/assign these requests to the user that generated the User access token. Before making requests to the Purchase Request API, you must obtain an access token from the Authentication API.
The response will include an access_token field, which contains your access token. For subsequent calls, you will need to include this access token in the Authorization header of your calls. An id_token will be also included in the response. In order to retrieve the unique ID for your user, you will have to decode this id_token at jwt.io. You will need this ID in order to post Purchase Requests.
Purchase Request v4 - Endpoints
- Create a New Purchase Request
- Get Purchase Request Details
- Schema
- Error Codes When the HTTP Status Code is 4xx
Version
4.0
Purchase Request v4 - Endpoints - Create a New Purchase Request
Create a Purchase Request based on provided header and line item details. If the request is valid it creates a purchase request and returns back a unique identifier to get the purchase request details.
Scopes
purchaserequest.write - Refer to Scope Usage for full details.
Request
URI
Template
POST /purchaserequest/v4/purchaserequests
Parameters
None
Headers
- RFC 7231 Content-Type
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the Company or User access token.
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
Response
Status Codes
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Content-Type
- RFC 7230 Content-Length
- RFC 7231 Date
- RFC 7231 Server
Payload
Example
Request
This is a sample set of fields. The fields and values your entity requires will vary based on your edition of Concur Invoice, and your forms and fields configuration. This example includes commonly used fields.
POST /purchaserequest/v4/purchaserequests
Authorization: Bearer {token}
Content-Type: application/json
{
"description" : "New office supplies",
"userLoginId" : "john.deo@concur",
"policyExternalId" : "po-external-id",
"currencyCode" : "USD",
"notesToSupplier" : "Office space request phase 1",
"comments" : "office supplies request",
"custom1" : "ADVT",
"shipToAddressCode" : "SHIP15139",
"billToAddressCode" : "MNSLP129",
"lineItems" : [
{
"purchaseType" : "SERVICES",
"vendorCode" :"VEN1",
"vendorAddressCode" : "ADDR1",
"description" : "monitor",
"quantity" : "20",
"unitPrice" : "154.4",
"expenseType" : "1250",
"receiptType" : "NONE",
"neededByDate": "2018-06-28",
"uomCode" : "DA",
"shipping" : "13.5",
"tax" : "11",
"supplierPartId" : "DAQT1",
"url" :[
"http://officesupplies.com/monitor"
],
"notesToVendor" : "Phase 1 request monitor",
"comments" : "Phase 1 request for new employees for monitor",
"custom2" : "LGVT1"
},
{
"purchaseType" : "GOODS",
"vendorCode" :"VEN1",
"vendorAddressCode" : "ADDR1",
"description" : "office chair",
"quantity" : "20",
"unitPrice" : "346.2",
"expenseType" : "1251",
"receiptType" : "QUANTITY_RECEIPT",
"neededByDate": "2018-06-28",
"uomCode" : "DA",
"shipping" : "15",
"tax" : "17.5",
"supplierPartId" : "DAQT2",
"url" :[
"http://officesupplies.com/officechair"
],
"notesToVendor" : "Phase 1 request office chair",
"comments" : "Phase 1 request for new employees for office chair",
"custom3" : "DEPT",
"custom4" : "SALES"
}
]
}
Response
HTTP/1.1 202 Accepted
Content-Type: application/json
Date: date-requested
Content-Length: 1000
concur-correlationid: 1234abcd-12ab-34cd-56ef-123456abcdef
{
"id" : "b1e22581-ff4a-48e9-981b-2f5065579096",
"uri": "http://us.api.concursolutions.com/purchaserequest/v4/purchaserequests/b1e22581-ff4a-48e9-981b-2f5065579096?mode=COMPACT"
}
Purchase Request v4 - Endpoints - Get Purchase Request Details
Gets purchase request details. The supported mode is COMPACT, which returns basic info about the purchase request along with any exceptions.
Scopes
purchaserequest.read - Refer to Scope Usage for full details.
Request
URI
Template
GET /purchaserequest/v4/purchaserequests/{id}?mode=COMPACT
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
mode |
string |
- | Required: Specifies mode for Get Purchase Request Details. Supported value: COMPACT |
Headers
- RFC 7231 Content-Type
- RFC 7235 Authorization - Bearer Token that identifies the caller. This is the Company or User access token.
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace
Payload
None
Response
Status Codes
Headers
concur-correlationidis a Concur specific custom header used for technical support in the form of a RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace- RFC 7231 Content-Type
- RFC 7230 Content-Length
- RFC 7231 Date
- RFC 7231 Server
Payload
Example
Request
GET /purchaserequest/v4/purchaserequests/de9c0894-b807-6943-8e3f-49a707da3456?mode=COMPACT
Authorization: Bearer {token}
Content-Type: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json
Date: date-requested
Content-Length: 1000
concur-correlationid: 1234abcd-12ab-34cd-56ef-123456abcdef
{
"purchaseRequestId" : "de9c0894-b807-6943-8e3f-49a707da3456",
"purchaseRequestNumber" : "100000",
"purchaseRequestQueueStatus" : "CREATED",
"purchaseRequestWorkflowStatus" : "Approved",
"purchaseRequestExceptions": [
{
"message": "Line Item Quantity does not match",
"eventCode": "PURCH_DETAIL_ITEM_SAVE",
"exceptionCode": "0070071",
"isCleared": false,
"prExceptionId": "fe636831-43a1-9540-bf86-32e2c19400af"
}
],
"purchaseOrders": [
{
"purchaseOrderNumber": "PO10001"
}
]
}
Purchase Request v4 - Endpoints - Schema
Create Purchase Request Schema
| Name | Type | Format | Description |
|---|---|---|---|
userId |
string |
- | Required: The employee that is requesting the items. This is the UUID of the employee. Either UserId or UserEmail or UserLoginId is required to identify the employee. |
userEmail |
string |
- | Required: The employee that is requesting the items. This is the employee's email. Either UserId or UserEmail or UserLoginId is required to identify the employee. |
userLoginId |
string |
- | Required: The employee that is requesting the items. This is the employee's Login Id. Either UserId or UserEmail or UserLoginId is required to identify the employee. |
description |
string |
- | A description of the purchase request. |
policyExternalId |
string |
- | The external identifier of the policy that should be associated with the purchase request. If not supplied, the API will use the default policy set up for the user group assigned to the requesting employee. This is the External Id from the Invoice Policy configuration. Clients will need to get these Ids from their SAP Concur contact if they need to assign policies other than the group default. |
currencyCode |
string |
- | Required: The 3-letter ISO 4217 currency code of the currency that is associated with the purchase request. This code will be used for all items on this request. Example: USD |
notesToSupplier |
string |
- | Notes to print on the transmitted purchase order PDF sent to the supplier. |
comments |
string |
- | Internal comments related to this record. |
custom1 through custom24 |
string |
- | Each custom field used should have its own row in the message. If the field is tied to a connected list, the accepted value is the list Item Code configured for the list in SAP Concur. |
shipToAddressCode |
string |
- | The shipping address of the Purchase Request. The accepted value is the address code from ShipTo record. If not supplied, the API will use the requesting user's default shipping address. |
billToAddressCode |
string |
- | The billing address of the Purchase Request to be used for invoicing. The accepted value is the address code from the BillTo record. If not supplied the API will use the policy's default BillTo address. |
lineItems |
array |
LineItem |
Required: Requested items or services related to this Purchase Request. |
LineItem
| Name | Type | Format | Description |
|---|---|---|---|
purchaseType |
string |
- | Required: The type of item, either goods or services. Displayed as Type in Concur Invoice. Supported values: GOODS, SERVICES. |
vendorCode |
string |
- | Required: The code that identifies the vendor. This value can be found in the vendor information form of Vendor Manager. This is used along with Vendor Address Code to determine the specific Vendor record. |
vendorAddressCode |
string |
- | Required: The code that identifies the vendor's address. This value can be found in the vendor information form of Vendor Manager and is labeled Address Accounting Code. This is used along with Vendor Code to determine the specific Vendor record. |
description |
string |
- | Required: A description of the line item. |
quantity |
decimal |
- | Required: The quantity associated with the line item. |
unitPrice |
decimal |
- | Required: The unit price of the line item. |
expenseType |
string |
- | The PET code of the Expense Type that will be assigned to the line item. If not supplied it will default to the Expense Type set up on the Vendor Profile used for the item. Clients will need to get these PET codes from their SAP Concur contact. |
receiptType |
string |
- | The type of receipt. If not supplied, the API will use the purchaseType to set this field to NONE for SERVICES, or QUANTITY_RECEIPT for GOODS. If you are using SAP Concur Receiving and need to enter Goods Receipts against the resulting PO lines use QUANTITY_RECEIPT. Supported values: QUANTITY_RECEIPT, NONE. |
neededByDate |
date |
YYYY-MM-DD | The date by which the purchase order must be fulfilled. Example: 2018-03-23 |
uoMCode |
string |
- | Unit of Measure (UOM) code for the purchase request item. Accepted values are the UOM Codes set up in the Unit of Measure configuration in Concur Invoice. If not supplied, the API will default a UOM based on the defaults for goods and services. |
shipping |
decimal |
- | The total shipping cost for the item. |
tax |
decimal |
- | Tax amount that is associated with the line item. |
supplierPartId |
string |
- | An Id value that helps to identify the line item. This could be a value such as the vendor’s part number or the manufacturer number. |
url |
array |
- | A URL related to the item. You can have multiple URLs per item, enclosed in quotes and comma separated. |
notesToVendor |
string |
- | Notes related to the item that display on the transmitted purchase order PDF to the vendor. |
comments |
string |
- | Internal comments related to this record. |
custom1 through custom20 |
string |
- | Each custom field used should have its own row in the message. If the field is tied to a connected list, the accepted value is the List Item Code configured for the list in SAP Concur. |
Create Purchase Request Response Schema
| Name | Type | Format | Description |
|---|---|---|---|
errors |
array |
Error |
An array of errors indicating which fields have failed validation. |
id |
string |
- | The unique purchase request reference ID if the request has passed all validations. This reference ID will be needed to look up details of the purchase request. |
uri |
string |
- | The URI to look up details of the newly created purchase request. |
Get Purchase Request Response Schema
| Name | Type | Format | Description |
|---|---|---|---|
purchaseRequestId |
string |
- | The unique purchase request reference Id. Returned by the Create Purchase Request API call. |
purchaseRequestNumber |
string |
- | The unique purchase request identifier which can be used to uniquely identify a purchase request in SAP Concur products. |
purchaseRequestQueueStatus |
string |
- | The creation status of the purchase request. Possible values are: PENDING_CREATION, CREATED, CREATE_FAILED. |
purchaseRequestWorkflowStatus |
string |
- | The workflow status of the purchase request. Possible values are: Approved, Pending Approval, Pending Cost Object Approval, Sent Back To Employee, Not Submitted, Submitted, Pending Processor Review, Vendor Approval, Approval Time Expired. |
purchaseOrders |
array |
PurchaseOrders |
If the purchase request has been approved and a purchase order generated, this array contains the purchase order details. If empty, this element will not be returned. |
purchaseRequestExceptions |
array |
PurchaseRequestExceptions |
An array of exceptions, if present on the purchase request. If empty, this element will not be returned. |
PurchaseOrders
| Name | Type | Format | Description |
|---|---|---|---|
purchaseOrderNumber |
string |
- | The purchase order number. |
PurchaseRequestExceptions
| Name | Type | Format | Description |
|---|---|---|---|
eventCode |
string |
- | The event code of the exception. Example: PURCH_DETAIL_SUBMIT |
exceptionCode |
string |
- | The unique exception code. |
isCleared |
boolean |
- | Whether the exception has been cleared. |
prExceptionId |
string |
- | The unique exception id of the purchase request. |
message |
string |
- | The message of the exception with details. |
Purchase Request v4 - Endpoints - Error
| Name | Type | Format | Description |
|---|---|---|---|
errorCode |
string |
- | An error code indicating why a field failed validation. |
errorMessage |
string |
- | A description of the error. |
dataPath |
string |
- | The path to the request data which has the error message. |
Error Codes When the HTTP Status Code is 4xx
| ErrorCode | Error Message |
|---|---|
| missingRequestBody | Missing request body. |
| invalidRequestBody | Passed request body is invalid. |
| missingUserInfo | Either userID or userEmail or userLoginId is required. |
| invalidUserInfo | Either userID or userEmail or userLoginId is invalid, or user does not have access to this resource. |
| provideOneUserInformation | Either userID or userEmail or userLoginId is required. |
| missingCurrencyCode | currencyCode is missing. |
| invalidCurrencyCode | currencyCode is invalid. |
| invalidPolicyInformation | Cannot find a purchase order policy with the supplied policyExternalId. |
| missingLineItems | lineItems are missing. |
| invalidPurchaseType | purchaseType is invalid. |
| missingPurchaseType | purchaseType is required. |
| missingVendorAddressCode | vendorAddressCode is required. |
| missingVendorCode | vendorCode is required. |
| invalidVendor | Vendor / Address code combination is invalid. |
| missingDescription | Line item description is required. |
| missingQuantity | Line item quantity is required. |
| invalidQuantity | Line item quantity is invalid. |
| missingUnitPrice | unitPrice is required. |
| invalidUnitPrice | unitPrice is invalid. |
| invalidDateFormat | Expected a date in the format YYYY-MM-DD. |
Purchase Order Receipt v3
Purchase order receipts are records that indicate purchase order lines were completed and received. This API provides methods to create a new purchase order receipt, and retrieve, update, or delete an existing purchase order receipt.
- Create a new purchase order receipt
- Update purchase order line item-receipt information
- Get existing purchase order receipt
- Delete existing purchase order receipt
- Schema
- Response schema
- Receipt schema
- Error codes
Version
3.0
Create a new purchase order receipt
POST /api/v3.0/invoice/purchaseorderreceipts
Creates purchase order receipt, associates it to purchase order line item, and returns update status.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
purchaseOrderReceipt |
- | body |
The details of the purchase order receipt. |
Input
{
"Deleted": "false",
"DeliverySlipNumber": "DSN1",
"GoodsReceiptNumber": "RCPT1",
"ID": "1000001",
"LineItemExternalID": "LN000001",
"PurchaseOrderNumber": "PO12345",
"ReceivedDate": "2018-09-15 00:00:00.0",
"ReceivedQuantity": "14.5",
"UnitOfMeasureCode": "DA",
"URI": "string",
"Version": "2.0"
}
Response
Update purchase order line item - receipt information
PUT /api/v3.0/invoice/purchaseorderreceipts
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
purchaseOrderReceipt |
- | body |
Purchase order receipt information. |
Input
Response
Get existing purchase order receipt
GET /api/v3.0/invoice/purchaseorderreceipts?purchaseOrderNumber=PO1&lineItemExternalID=L1&goodsReceiptNumber=GRN1
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
purchaseOrderNumber |
string |
{purchaseOrderNumber} | The purchase order number. |
lineItemExternalID |
string |
{lineItemExternalID} | A customer-supplied value that uniquely identifies the line item within the purchase order. |
goodsReceiptNumber |
string |
{goodsReceiptNumber} | Goods receipt number for a purchase order line item receipt. |
Input
None.
Response
Delete existing purchase order receipt
DELETE /api/v3.0/invoice/purchaseorderreceipts?purchaseOrderNumber=PO1&lineItemExternalID=L1&goodsReceiptNumber=GRN1
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
purchaseOrderNumber |
string |
{purchaseOrderNumber} | The purchase order number. |
lineItemExternalID |
string |
{lineItemExternalID} | A customer-supplied value that uniquely identifies the line item within the purchase order. |
goodsReceiptNumber |
string |
{goodsReceiptNumber} | Goods receipt number for a purchase order line item receipt. |
Input
None.
Response
Purchase Order Receipt v3 - Response schema
| Name | Type | Format | Description |
|---|---|---|---|
ErrorCode |
string |
- | A code that indicates why the purchase order receipt was not processed successfully. |
ErrorMessage |
string |
- | A description of the error. |
FieldCode |
string |
- | A code that indicates which field caused an issue. This code typically appears only when a field is being validated against a field of a form type. |
LineItemExternalID |
string |
- | The external ID of a line item that caused an error. |
Message |
string |
- | Message of request result. |
PurchaseOrderNumber |
string |
- | The purchase order number. |
Status |
string |
- | The result of processing the purchase order receipt. Format: SUCCESS or FAILURE |
Get Purchase Order Receipt schema
| Name | Type | Format | Description |
|---|---|---|---|
purchaseOrderReceipt |
array |
PurchaseOrderReceipt |
Purchase Order Receipt. |
NextPage |
string |
- | The URI of the next page of results, if any. |
TotalCount |
int |
- | Total number of receipts. |
Info |
string |
- | Any additional information messages. Currently a maximum of 2000 PO receipts will be returned. |
Purchase Order Receipt v3 - Receipt schema
| Name | Type | Format | Description |
|---|---|---|---|
Deleted |
boolean |
- | Delete status of purchase order line item receipt. |
DeliverySlipNumber |
string |
- | Delivery slip number for a purchase order line item receipt. |
GoodsReceiptNumber |
string |
- | Goods receipt number for a purchase order line item receipt. |
ID |
string |
- | The unique identifier of the resource. |
LineItemExternalID |
string |
- | Required A customer-supplied value that uniquely identifies the line item within the purchase order. |
PurchaseOrderNumber |
string |
- | Required The purchase order number. |
ReceivedDate |
string |
- | The date the line item was received. Format: YYYY-MM-DD |
ReceivedQuantity |
string |
- | The number of items that were received. |
UnitOfMeasureCode |
string |
- | Unit of measure code for a purchase order line item receipt. |
URI |
string |
- | The URI to the resource. |
Version |
string |
- | The version of purchase order line item receipt. Use Version 2.0 here unless doing receipt confirmation only. |
Purchase Order Receipt v3 - Error codes
The Purchase Order Receipt API’s error responses
| Code | Description |
|---|---|
| 1000 | The PO number is missing or invalid. |
| 1001 | The External ID is missing or invalid. |
| 1002 | The Is Received is invalid. It must be either empty, Y/N, or y/n. |
| 1003 | The Received Quantity is invalid. It must be either empty or numeric. |
| 1004 | The Received Date is invalid. It must be either empty or date formatted YYYY-MM-DD. |
| 1005 | The Unit Of Measure code is invalid. It must be either empty or Valid with less than 10 chars in length. |
| 1006 | The Received Quantity is invalid, for Receipt Type WQTY on Purchase Order, Quantity is required. Sorry. |
| 1007 | The field is not part of the form |
| 1008 | The value exceeds the maximum length allowed for the field. |
| 1009 | The value is the wrong data type for the field. |
| 1011 | The invalid value expression. |
| 9999 | An unexpected error occurred. |
| 10010 | The required field is missing. |
Sales Tax Validation v3
Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API. This API is not available in Implementation environments.
- Products and Editions
- Scope Usage
- Dependencies
- Get Invoices for Calculating Tax
- Update Invoices with the Calculated Tax Amount and Tax Rate
- Schema
- Status Schema
Sales Tax Validation v3 - Products and Editions
- Concur Invoice Professional Edition
Sales Tax Validation v3 - Scope Usage
| Name | Description | Endpoint |
|---|---|---|
INVTV |
Invoice - Tax Validation | GET, PUT |
Sales Tax Validation v3 - Dependencies
None.
Get Invoices for Calculating Tax
Retrieves invoices for calculating tax.
Scopes
INVTV - Refer to Scope Usage for full details.
Request
URI
Template
https://{datacenterURI}/api/v3.0/invoice/salestaxvalidationrequest
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
offset |
string |
query |
The starting point of the next set of results, after the limit specified in the limit field has been reached. |
limit |
Int32 |
query |
The number of invoices to retrieve. Maximum value: 1,000 |
modifiedafter |
string |
query |
A parameter that can be used to limit the results to invoices modified after the specified date. |
Payload
- None.
Response
Payload
Example
Request
https://us.api.concursolutions.com/api/v3.0/invoice/salestaxvalidationrequest
Response
{
"TotalCount": 1,
"Items": [
{
"RequestID": "3E6969DD15D64A349188",
"TaxReferenceID": "9B8888FA54CA47E598081F4527A2BC50",
"CountryCode": "US",
"Title": "Test Request - 15 Feb",
"PurchaseOrderNumber": null,
"InvoiceDate": "2019-03-01 00:00:00.0",
"StatusCode": null,
"Status": null,
"InvoiceAmount": "480.00000000",
"Total": "500.00000000",
"ShippingAmount": "0.00000000",
"Tax": "20.00000000",
"CalculatedTaxAmount": null,
"CalculatedTaxRate": null,
"CurrencyCode": "USD",
"VendorInvoiceNumber": "99999",
"OrgUnit1": "1",
"OrgUnit1Value": "Best Buy",
"OrgUnit2": "100",
"OrgUnit2Value": "Geek Squad",
"OrgUnit3": null,
"OrgUnit3Value": null,
"OrgUnit4": null,
"OrgUnit4Value": null,
"OrgUnit5": null,
"OrgUnit5Value": null,
"OrgUnit6": null,
"OrgUnit6Value": null,
"Custom1": null,
"Custom1Value": null,
"Custom2": null,
"Custom2Value": null,
"Custom3": null,
"Custom3Value": null,
"Custom4": null,
"Custom4Value": null,
"Custom5": null,
"Custom5Value": null,
"Custom6": null,
"Custom6Value": null,
"Custom7": null,
"Custom7Value": null,
"Custom8": null,
"Custom8Value": null,
"Custom9": null,
"Custom9Value": null,
"Custom10": null,
"Custom10Value": null,
"Custom11": null,
"Custom11Value": null,
"Custom12": null,
"Custom12Value": null,
"Custom13": null,
"Custom13Value": null,
"Custom14": null,
"Custom14Value": null,
"Custom15": null,
"Custom15Value": null,
"Custom16": null,
"Custom16Value": null,
"Custom17": null,
"Custom17Value": null,
"Custom18": null,
"Custom18Value": null,
"Custom19": null,
"Custom19Value": null,
"Custom20": null,
"Custom20Value": null,
"Custom21": null,
"Custom21Value": null,
"Custom22": "Default",
"Custom22Value": "Default-Change to Client",
"Custom23": null,
"Custom23Value": null,
"Custom24": null,
"Custom24Value": null,
"BillToAddress": {
"ExternalID": null,
"Name": null,
"Address1": null,
"Address2": null,
"Address3": null,
"City": null,
"StateProvince": null,
"State": null,
"PostalCode": null,
"CountryCode": null
},
"ShipToAddress": {
"ExternalID": null,
"Name": null,
"Address1": "BTP",
"Address2": null,
"Address3": null,
"City": "Bengaluru South",
"StateProvince": null,
"State": null,
"PostalCode": "560093",
"CountryCode": "IN"
},
"LineItem": [
{
"CommodityCode": "95121513",
"Quantity": "1.00000000",
"LineItemKey": "gWo0fa6rk0zJkpaD3ZXHL8DbNaw",
"UnitPrice": "200.00000000",
"Total": "200.00000000",
"CountryCode": "US",
"CalculatedTaxAmount": null,
"CalculatedTaxRate": null,
"CurrencyCode": "USD",
"Allocations": {
"Allocation": [
{
"Custom1": "1",
"Custom1Value": null,
"Custom2": "100",
"Custom2Value": null,
"Custom3": null,
"Custom3Value": null,
"Custom4": null,
"Custom4Value": null,
"Custom5": null,
"Custom5Value": null,
"Custom6": null,
"Custom6Value": null,
"Custom7": null,
"Custom7Value": null,
"Custom8": null,
"Custom8Value": null,
"Custom9": null,
"Custom9Value": null,
"Custom10": null,
"Custom10Value": null,
"Custom11": null,
"Custom11Value": null,
"Custom12": null,
"Custom12Value": null,
"Custom13": null,
"Custom13Value": null,
"Custom14": null,
"Custom14Value": null,
"Custom15": null,
"Custom15Value": null,
"Custom16": null,
"Custom16Value": null,
"Custom17": null,
"Custom17Value": null,
"Custom18": null,
"Custom18Value": null,
"Custom19": null,
"Custom19Value": null,
"Custom20": null,
"Custom20Value": null,
"AllocationAmount": "200.00000000"
}
]
},
"Vendor": {
"VendorCode": null,
"VendorName": "Holiday Inn",
"VendorAddressName": null,
"AddressCode": null,
"Address1": null,
"Address2": null,
"Address3": null,
"City": null,
"State": null,
"PostalCode": null,
"CountryCode": null
}
},
{
"CommodityCode": "90111501",
"Quantity": "1.00000000",
"LineItemKey": "gWo0c5$sMJswx4W0tK$pw2bwBTFtQ",
"UnitPrice": "280.00000000",
"Total": "280.00000000",
"CountryCode": "US",
"CalculatedTaxAmount": null,
"CalculatedTaxRate": null,
"CurrencyCode": "USD",
"Allocations": {
"Allocation": [
{
"Custom1": "1",
"Custom1Value": null,
"Custom2": "100",
"Custom2Value": null,
"Custom3": null,
"Custom3Value": null,
"Custom4": null,
"Custom4Value": null,
"Custom5": null,
"Custom5Value": null,
"Custom6": null,
"Custom6Value": null,
"Custom7": null,
"Custom7Value": null,
"Custom8": null,
"Custom8Value": null,
"Custom9": null,
"Custom9Value": null,
"Custom10": null,
"Custom10Value": null,
"Custom11": null,
"Custom11Value": null,
"Custom12": null,
"Custom12Value": null,
"Custom13": null,
"Custom13Value": null,
"Custom14": null,
"Custom14Value": null,
"Custom15": null,
"Custom15Value": null,
"Custom16": null,
"Custom16Value": null,
"Custom17": null,
"Custom17Value": null,
"Custom18": null,
"Custom18Value": null,
"Custom19": null,
"Custom19Value": null,
"Custom20": null,
"Custom20Value": null,
"AllocationAmount": "280.00000000"
}
]
},
"Vendor": {
"VendorCode": null,
"VendorName": "Holiday Inn",
"VendorAddressName": null,
"AddressCode": null,
"Address1": null,
"Address2": null,
"Address3": null,
"City": null,
"State": null,
"PostalCode": null,
"CountryCode": null
}
}
],
"ID": null,
"URI": null
}
],
"NextPage": null
}
JSON Example of an Unsuccessful Response
{
"Error": {
"Message": "Forbidden Request",
"Server-Time": "2019-03-12T07:56:32",
"Id": "65F68719-3FF5-459E-8B94-5FC93A5CD045"
}
}
Update Invoices with a Calculated Tax Amount and Tax Rate
Updates invoices with calculated tax amount and tax rate.
Scopes
INVTV - Refer to Scope Usage for full details.
Request
URI
Template
https://{datacenterURI}//api/v3.0/invoice/salestaxvalidationrequest
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
invoice |
- | body |
The tax information for the invoice that is to be updated. |
Payload
Response
Payload
Example
Request
{
"CalculatedTaxAmount": "150.00",
"CalculatedTaxRate": "0.40",
"Comments": "Updating Calculated Tax",
"LineItem": [
{
"CalculatedTaxAmount": "50.00",
"CalculatedTaxRate": "0.05",
"LineItemKey": "gWo0b$sLeIU2W18zqlQiELsE7TvQ"
}
],
"StatusCode": "CMPLT",
"TaxReferenceID": "9A0F8C3EDF4040BBA94394A1A0CA6DCB"
}
Response
{
"TaxReferenceID": "9A0F8C3EDF4040BBA94394A1A0CA6DCB",
"Comments": null,
"Status": "SUCCESS",
"Type": null,
"Code": 0,
"Message": null,
"Parameters": null,
"RecordNumber": 0
}
JSON Example of an Unsuccessful Response
{
"Message": " Status code is a required field. ERROR,CMPLT are valid values."
}
Invoices Schema
Sales Tax Validation v3 - Invoices
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Invoice |
The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
TotalCount |
Int32 |
- | The amount of items returned. |
Invoice
| Name | Type | Format | Description |
|---|---|---|---|
BillToAddress |
object |
BillToAddress |
The billing address associated with the invoice. |
CalculatedTaxAmount |
string |
- | The calculated tax amount for the invoice. |
CalculatedTaxRate |
string |
- | The calculated tax rate for the invoice. |
Comments |
string |
- | Comments for the invoice. |
CountryCode |
string |
- | The country code for the line item. |
CurrencyCode |
string |
- | The 3-letter ISO 4217 currency code for the invoice currency. Example: USD, CAD |
ID |
string |
- | The unique identifier of the resource. |
InvoiceAmount |
string |
- | The invoice amount (the cost of the purchased items). |
InvoiceDate |
string |
- | The date of the invoice. |
LineItem |
array |
LineItem |
The line items associated with the invoice. |
OrgUnit1 through OrgUnit6 |
string |
- | Not available for PUT. The code from the OrgUnit fields. These fields may not have data, depending on the configuration. |
OrgUnit1Value though OrgUnit6Value |
string |
- | Not available for PUT. The value from the OrgUnit fields. These fields may not have data, depending on the configuration. |
Custom1 through Custom24 |
string |
- | Not available for PUT. The code from the Custom fields. These fields may not have data, depending on the configuration. |
Custom1Value through Custom24Value |
string |
- | Not available for PUT. The value from the Custom fields. These fields may not have data, depending on the configuration. |
PurchaseOrderNumber |
string |
- | The purchase order number associated to the invoice. |
RequestID |
string |
- | The ID of the invoice. |
ShippingAmount |
string |
- | The shipping amount for the invoice. |
ShipToAddress |
object |
ShipToAddress |
The shipping address associated with the invoice. |
Status |
string |
- | The status of the invoice. |
StatusCode |
string |
- | Required The status code for the invoice. Supported values: ERROR, CMPLT |
Tax |
string |
- | The tax, as shown on the invoice. This is the tax applied by the vendor. |
TaxReferenceID |
string |
- | Required The tax reference ID of the invoice. |
Title |
string |
- | The title of the invoice. |
Total |
string |
- | The total amount of the invoice. |
URI |
string |
- | The URI to the resource. |
VendorInvoiceNumber |
string |
- | The vendor invoice number that is associated with the invoice. |
Sales Tax Validation v3 - BillToAddress
| Name | Type | Format | Description |
|---|---|---|---|
Address1 |
string |
- | Required Address line 1 of the billing address. |
Address2 |
string |
- | Address line 2 of the billing address. |
Address3 |
string |
- | Address line 3 of the billing address. |
City |
string |
- | Required The city of the billing address. |
CountryCode |
string |
- | Required The code of the country for the billing address. |
ExternalID |
string |
- | Required A unique value supplied by the customer to identify a particular billing address. |
Name |
string |
- | An optional name that can be given to the billing address. |
PostalCode |
string |
- | Required The postal code of the billing address. |
State |
string |
- | Required The state of the billing address. |
StateProvince |
string |
- | Required The province of the billing address. |
Sales Tax Validation v3 - LineItem
| Name | Type | Format | Description |
|---|---|---|---|
Allocations |
object |
Allocation |
The allocations associated with a line item. |
CalculatedTaxAmount |
string |
- | The calculated tax amount for the individual line item. |
CalculatedTaxRate |
string |
- | The calculated tax rate for the individual line item. |
CommodityCode |
string |
- | The commodity code that is tied to the expense type associated with the line item. |
CountryCode |
string |
- | The country code for the line item. |
CurrencyCode |
string |
- | The currency code for the individual line item. |
LineItemKey |
string |
- | Required A value that uniquely identifies the line item. |
Quantity |
string |
- | The quantity for the line item. |
Total |
string |
- | The total amount for the line item. |
UnitPrice |
string |
- | The unit price for the line item. |
Vendor |
object |
InvoiceVendor |
Details about the vendor for each line item. |
Sales Tax Validation v3 - Allocation
| Name | Type | Format | Description |
|---|---|---|---|
AllocationAmount |
string |
- | The allocation amount associated with the line item. |
Custom1 through Custom20 |
string |
- | Not available for PUT. The code from the Custom fields. These fields may not have data, depending on the configuration. |
Custom1Value through Custom20Value |
string |
- | Not available for PUT. The value from the Custom fields. These fields may not have data, depending on the configuration. |
Sales Tax Validation v3 - Vendor
| Name | Type | Format | Description |
|---|---|---|---|
Address1 |
string |
- | Required Address line 1 of the vendor address. |
Address2 |
string |
- | Address line 2 of the vendor address. |
Address3 |
string |
- | Address line 3 of the vendor address. |
City |
string |
- | Required The city of the vendor address. |
CountryCode |
string |
- | Required The code of the country for the vendor address. |
PostalCode |
string |
- | Required The postal code of the vendor address. |
State |
string |
- | Required The state of the vendor address. |
VendorAddressName |
string |
- | Required The name for the vendor address. |
VendorName |
string |
- | Required The name of the vendor. |
VendorCode |
string |
- | Required The code associated with the vendor. |
Sales Tax Validation v3 - ShipToAddress
| Name | Type | Format | Description |
|---|---|---|---|
Address1 |
string |
- | Required Address line 1 of the shipping address. |
Address2 |
string |
- | Address line 2 of the shipping address. |
Address3 |
string |
- | Address line 3 of the shipping address. |
City |
string |
- | Required The city of the shipping address. |
CountryCode |
string |
- | Required The code of the country for the shipping address. |
ExternalID |
string |
- | Required A unique value supplied by the customer to identify a particular shipping address. |
Name |
string |
- | An optional name that can be given to the shipping address. |
PostalCode |
string |
- | Required The postal code of the shipping address. |
State |
string |
- | Required The state of the shipping address. |
StateProvince |
string |
- | Required The province of the shipping address. |
Status Schema
| Name | Type | Format | Description |
|---|---|---|---|
Code |
int |
- | Code of request result. |
Comments |
string |
- | Comments that are returned for the update request. |
Message |
string |
- | Message of request result. |
RecordNumber |
int |
- | Record number for the create/update request. |
Status |
string |
- | The status of the update. Supported values: SUCCESS, FAILURE |
TaxReferenceID |
string |
- | The tax reference ID of the updated invoice. |
Type |
string |
- | Type request result. |
Vendor v3
The Vendor API allows you to develop processes that can be used to manage your Vendor collection for invoicing, adding new Vendors, updating, getting, or deleting information for existing Vendors.
Limitations: This API is only available to partners who have been granted access by SAP Concur. Access to this documentation does not provide access to the API. This API is not available in the China data center.
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
- Retrieve an existing vendor
- Create vendors
- Update existing vendors
- Delete vendors
- Add/Update Vendor Banking
- Add Vendor Group
- Delete Vendor Group
- Schema
Vendor v3 - Products and Editions
- Concur Invoice Professional Edition
- Concur Invoice Standard Edition
Vendor v3 - Scope Usage
| Name | Description | Endpoint |
|---|---|---|
INVVEN |
Retrieves vendor information. | GET |
Vendor v3 - Dependencies
SAP Concur clients must purchase Concur Invoice in order to use this API.
Vendor v3 - Access Token Usage
This API supports both company level and user level access tokens.
Retrieve an Existing Vendor
Note: If authenticating with a Company access token the API will return all vendors associated with a specific entity.
GET /api/v3.0/invoice/vendors
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
limit |
Int32 |
query |
The maximum number of items to be returned in a response. The default is 25 and cannot exceed 1000. |
offset |
string |
query |
Specifies the starting point for the next query when iterating through the collection response. Use with paged collections of resources. |
sortDirection |
string |
query |
Ascending or descending, The default value will be ascending. |
sortBy |
string |
query |
Field you need the results to be sorted by. Vendor Name will be made default if no value is sent. Only fields that are added to the vendor form can be used here. Fields have to be specified by name as specified in Doc. |
searchType |
string |
query |
Applies for the entire given search parameters. The default value is exact. Supported values: exact, begins, contains, ends |
vendorCode |
string |
query |
Vendor Code to be searched |
vendorName |
string |
query |
Vendor Name to be searched |
taxID |
string |
query |
Tax ID to be searched |
buyerAccountNumber |
string |
query |
Buyer Account Number to be searched |
paymentMethodType |
string |
query |
Payment Method Type - valid values are ACH, CARD, CHECK, CLIENT, PAYPVD, VCHER, WIRE |
addressCode |
string |
query |
Address Code to be searched |
address1 |
string |
query |
Address 1 to be searched |
address2 |
string |
query |
Address 2 to be searched |
address3 |
string |
query |
Address 3 to be searched |
city |
string |
query |
City to be searched |
state |
string |
query |
State to be searched |
postalCode |
string |
query |
Postal Code to be searched |
approved |
string |
query |
Find Approved/Unapproved Vendors, True/False |
country |
string |
query |
Country to be searched |
custom1 |
string |
query |
Custom 1 to be searched |
custom2 |
string |
query |
Custom 2 to be searched |
custom3 |
string |
query |
Custom 3 to be searched |
custom4 |
string |
query |
Custom 4 to be searched |
custom5 |
string |
query |
Custom 5 to be searched |
custom6 |
string |
query |
Custom 6 to be searched |
custom7 |
string |
query |
Custom 7 to be searched |
custom8 |
string |
query |
Custom 8 to be searched |
custom9 |
string |
query |
Custom 9 to be searched |
custom10 |
string |
query |
Custom 10 to be searched |
custom11 |
string |
query |
Custom 11 to be searched |
custom12 |
string |
query |
Custom 12 to be searched |
custom13 |
string |
query |
Custom 13 to be searched |
custom14 |
string |
query |
Custom 14 to be searched |
custom15 |
string |
query |
Custom 15 to be searched |
custom16 |
string |
query |
Custom 16 to be searched |
custom17 |
string |
query |
Custom 17 to be searched |
custom18 |
string |
query |
Custom 18 to be searched |
custom19 |
string |
query |
Custom 19 to be searched |
custom20 |
string |
query |
Custom 20 to be searched |
Input
None.
Response
Create Vendors
POST /api/v3.0/invoice/vendors Note: If authenticating with a Company access token, the API will create the requested Vendors.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
vendors |
- | body |
The vendor details. |
Input
Response
Update Existing Vendors
PUT /api/v3.0/invoice/vendors Note: If authenticating with a Company access token, the API will update the requested Vendors.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
vendors |
- | body |
The vendor details. |
Input
Response
Delete Vendor
DELETE /api/v3.0/invoice/vendors Note: If authenticating with a Company access token, the API will delete the requested Vendor.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
vendorCode |
string |
query |
Required Vendor Code to be deleted |
addressCode |
string |
query |
Required Address Code to be deleted |
Input
None.
Response
Add/Update Vendor Banking
PUT /api/v3.0/invoice/vendor/banks Note: If authenticating with a Company access token, the API will create / update the requested Vendor Banking info.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
vendorBanks |
- | body |
The vendor banking info |
Input
Response
Add Vendor Group
PUT /api/v3.0/invoice/vendor/groups Note: If authenticating with a Company access token, the API will create the requested Vendor groups.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
vendorCode |
string |
query |
Required The vendor code of the vendor to update |
addressCode |
string |
query |
Requred The address code of the vendor to update |
vendorGroups |
- | body |
The vendor group details |
Input
Response
Delete Vendor Group
DELETE /api/v3.0/invoice/vendor/groups Note: If authenticating with a Company access token, the API will delete the requested Vendor group.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
vendorCode |
string |
query |
Required The vendor code of the vendor to update |
addressCode |
string |
query |
Requred The address code of the vendor to update |
groupName |
string |
query |
Requred The group name to be deleted |
Input
None.
Response
Vendor v3 - Schema
Vendors
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
Vendor |
The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
RequestRunSummary |
string |
- | - |
TotalCount |
Int |
- | - |
Vendor |
array |
Vendor |
Required Vendor |
Vendor
| Name | Type | Format | Description |
|---|---|---|---|
AccountNumber |
string |
- | The Buyer Account Number. |
Address1 |
string |
- | The Vendor Address 1. |
Address2 |
string |
- | The Vendor Address 2. |
Address3 |
string |
- | The Vendor Address 3. |
AddressCode |
string |
- | Required The Address Code. |
AddressImportSyncID |
string |
- | This ID is originally generated by Invoice when an employee requests a new vendor. The Employee Request Vendor Extract provides this value to positively identify the vendor address record when reimporting vendor from the client's system of record for the Vendor Master List. |
Approved |
string |
- | Vendor Approval Status. |
City |
string |
- | The Vendor City. |
ContactEmail |
string |
- | The Vendor Contact Email. |
ContactFirstName |
string |
- | The Vendor Contact First Name. |
ContactLastName |
string |
- | The Vendor Contact Last Name. |
ContactPhoneNumber |
string |
- | The Vendor Contact Phone Number. |
Country |
string |
- | The Vendor Country. |
CountryCode |
string |
- | The Vendor Country Code. |
CurrencyCode |
string |
- | The Vendor Currency Code. |
Custom1 |
string |
- | A value that can be applied to a custom field 1 that is part of the vendor form. |
Custom10 |
string |
- | A value that can be applied to a custom field 10 that is part of the vendor form. |
Custom11 |
string |
- | A value that can be applied to a custom field 11 that is part of the vendor form. |
Custom12 |
string |
- | A value that can be applied to a custom field 12 that is part of the vendor form. |
Custom13 |
string |
- | A value that can be applied to a custom field 13 that is part of the vendor form. |
Custom14 |
string |
- | A value that can be applied to a custom field 14 that is part of the vendor form. |
Custom15 |
string |
- | A value that can be applied to a custom field 15 that is part of the vendor form. |
Custom16 |
string |
- | A value that can be applied to a custom field 16 that is part of the vendor form. |
Custom17 |
string |
- | A value that can be applied to a custom field 17 that is part of the vendor form. |
Custom18 |
string |
- | A value that can be applied to a custom field 18 that is part of the vendor form. |
Custom19 |
string |
- | A value that can be applied to a custom field 19 that is part of the vendor form. |
Custom2 |
string |
- | A value that can be applied to a custom field 2 that is part of the vendor form. |
Custom20 |
string |
- | A value that can be applied to a custom field 20 that is part of the vendor form. |
Custom3 |
string |
- | A value that can be applied to a custom field 3 that is part of the vendor form. |
Custom4 |
string |
- | A value that can be applied to a custom field 4 that is part of the vendor form. |
Custom5 |
string |
- | A value that can be applied to a custom field 5 that is part of the vendor form. |
Custom6 |
string |
- | A value that can be applied to a custom field 6 that is part of the vendor form. |
Custom7 |
string |
- | A value that can be applied to a custom field 7 that is part of the vendor form. |
Custom8 |
string |
- | A value that can be applied to a custom field 8 that is part of the vendor form. |
Custom9 |
string |
- | A value that can be applied to a custom field 9 that is part of the vendor form. |
DefaultEmployeeID |
string |
- | The Default Employee ID of the employee connected to the vendor. |
DefaultExpenseTypeName |
string |
- | The Default Expense Type tied to the vendor. |
DiscountPercentage |
string |
- | The Discount Percentage. |
DiscountTermsDays |
string |
- | The Vendor Discount Terms Days. |
ID |
string |
- | The unique identifier of the resource. |
IsLineItemVatIncld |
string |
- | Line item Unit Price Contains VAT , |
IsVisibleForContentExtraction |
string |
- | Flag that indicates if the vendor will be available for OCR within Brainware |
PaymentMethodType |
string |
- | Preferred Payment Type for Vendor. |
PaymentTerms |
Integer between 1 and 999 |
- | The Vendor Payment Terms. This field represents the number of days by which a payment must be made, for example, 30 days |
PostalCode |
string |
- | The Vendor Postal Code / Zip. |
ProvincialTaxID |
string |
- | The Vendor Provincial Tax ID. Note that this value is not encrypted at REST. |
PurchaseOrderContactEmail |
string |
- | The Purchase Order Contact Email. |
PurchaseOrderContactFirstName |
string |
- | The Purchase Order Contact First Name. |
PurchaseOrderContactLastName |
string |
- | The Purchase Order Contact Last Name. |
PurchaseOrderContactPhoneNumber |
string |
- | The Purchase Order Contact Phone Number. |
ShippingMethod |
string |
- | The Vendor Shipping Method. |
ShippingTerms |
string |
- | The Vendor Shipping Terms. |
State |
string |
- | The Vendor State. |
StatusList |
array |
Status |
Required Status results |
TaxID |
string |
- | The Vendor Tax ID. Note that this value is not encrypted at REST. |
TaxType |
string |
- | The Vendor Tax Type. |
URI |
string |
- | The URI to the resource. |
VendorBankList |
array |
VendorBank |
The list of a vendor's active banking information. Read-Only |
VendorCode |
string |
- | Required The vendor code of the request. |
VendorFormName |
string |
- | The vendor form name this vendor is associated with. |
VendorGroupList |
array |
- | The list of vendor groups by name. Read-Only |
VendorName |
string |
- | The name of the vendor. |
VoucherNotes |
string |
- | Notes sent to Vendor along with authorization to charge Card Voucher. |
Vendor Banking Input/Response Schema
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
VendorBank |
The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
RequestRunSummary |
string |
- | - |
TotalCount |
Int |
- | - |
VendorBank |
array |
VendorBank |
Required Vendor Banking Info |
VendorBank
| Name | Type | Format | Description |
|---|---|---|---|
AccountNumber |
string |
- | Required The account number. |
AccountType |
enum |
- | Required The account type--CHCK for Checking, SAVE for Savings. |
AddressCode |
string |
- | Required The Address Code. |
BankCode |
string |
- | Bank Code |
BankName |
string |
- | The bank name. |
BranchCode |
string |
- | Branch Code |
BranchLocation |
string |
- | The branch location |
CountryCode |
string |
- | The country code. |
CurrencyAlphaCode |
string |
- | The currency alpha Code. |
ID |
string |
- | The unique idenitifier of this resource. |
IsActive |
string |
- | Required Is information active |
NameOnAccount |
string |
- | Required The name on the account. |
RoutingNumber |
string |
- | The routing number. |
StatusList |
array |
status |
Status results |
TransType |
string |
- | The trans type. |
URI |
string |
- | The URI to the resource. |
VendorCode |
string |
- | Required The vendor code of the request. |
Vendor Group Input/Response Schema
| Name | Type | Format | Description |
|---|---|---|---|
Items |
array |
VendorGroup |
The result collection. |
NextPage |
string |
- | The URI of the next page of results, if any. |
RequestRunSummary |
string |
- | - |
TotalCount |
Int |
- | - |
VendorGroup |
array |
VendorGroup |
Required Vendor Group List |
VendorGroup
| Name | Type | Format | Description |
|---|---|---|---|
ID |
string |
- | The unique identifier of the resource. |
Name |
string |
- | Required The vendor group name. |
StatusList |
array |
status |
Status results. |
URI |
string | - | The URI to the resource. |
Status
| Name | Type | Format | Description |
|---|---|---|---|
Code |
int |
- | Code of request result |
Message |
string |
- | Message of request result |
RecordNumber |
int |
- | Record Number for create/update request. |
Type |
string |
- | Type request result |
Receipts
Get Started - Receipts v4
Receipts v4 - Overview
The Receipts V4 API accepts three different formulae for posting a receipt:
- Receipt Data - Your receipt data is stored along with an automatically generated receipt image file.
- Receipt Data & Receipt Image - Your receipt data and receipt image file are stored.
- Receipt Image w/o Data - Your receipt image file is stored along with some accompanying metadata.
All of the above are receipt resources, but the service draws a distinction between resources with data versus resources that are standalone images.
Resources with data are schema-enforced and are referred to as e-receipts.
Resources of standalone images are referred to as as Image-Only Receipts.
These two different resources are sent/fetched from the Receipts V4 API via different endpoints: * E-Receipts (Receipts With Data) - Use E-Receipt Endpoints * Image-Only Receipts (Standalone Images Without Data) - Use Image-Only Receipt Endpoints
Note: The Receipts V4 API only provides GET access to individual or user’s receipts that have been submitted through this API, and, therefore the response will not be comprehensive of every user receipt within SAP Concur. All other images should be obtained via the Image v1 API. Additionally, only the receipts will be returned, there will not be any corresponding entry data. Examples of Enterprise apps that should use the Image v1 API include: ERP integrations for financial journal entry postings, VAT reclaim integrations that obtain transactions to calculate VAT reclaim, project billing integrations used to substantiate expenses billed back, etc.
Receipts - Prior Versions
- Receipts v3 (Deprecated) documentation is available here
Get Started - Receipts v4 - Overview of Version 4.0
Version 4.0 of the Receipts API offers features like more receipt types, automatic e-receipt generation in end user’s preferred language and ability for partners to provide detailed tax information. Unlike version 3.0, we are discontinuing the use of matching facts; instead the partner will have to create a receipt for a specific end user. Receipts 4.0 works only with the new Authentication API.
Regional Availability
https://us.api.concursolutions.com/receipts/
https://emea.api.concursolutions.com/receipts/
Explore the API
Prerequisites
- Create a sandbox if you don't already have one.
- Read the Getting Started section of Authentication API.
Once you have registered your application, read about the API endpoints, or click the button to download a request collection for Postman.
Receipts v4 - Retrieve a User Access Token
Before making requests to the Receipts API, you must obtain an access token from the Authentication API.
The response will include an access_token field, which contains your access token. For subsequent calls, you will need to include this access token in the Authorization header of your calls. An id_token will be also included in the response. In order to retrieve the unique ID for your user, you will have to decode this id_token at jwt.io. You will need this ID in order to post receipts.
Examples:
cURL:
curl -d "client_secret={YOUR SECRET}&client_id={YOUR CLIENT ID}&grant_type=password&username={YOUR USERNAME}&password={YOUR PASSWORD}" https://us.api.concursolutions.com/oauth2/v0/token
HTTPie:
http -f POST https://us.api.concursolutions.com/oauth2/v0/token client_secret={YOUR SECRET} client_id={YOUR CLIENT ID} grant_type=password username={YOUR USERNAME} password=P{YOUR PASSWORD}
Explore the API in JavaScript
Below are some simple NodeJS code snippets for getting a token and posting a receipt.
Retrieve a User Access Token:
'use strict';
const request = require('request');
request.post({
url:'https://us.api.concursolutions.com/oauth2/v0/token',
form: {
client_secret: 'YOUR VALUE HERE',
client_id: 'YOUR VALUE HERE',
username: 'YOUR VALUE HERE',
password: 'YOUR VALUE HERE',
grant_type: 'password'
}},
(err, httpResponse, body) => {
if(err) { console.log(err); }
console.log('Status:', httpResponse.statusCode);
console.log('Response:', body);
});
Post a Receipt
'use strict';
const https = require('https');
const ACCESS_TOKEN = 'YOUR ACCESS TOKEN HERE';
const USER_ID = 'YOUR VALUE HERE';
const receipt = JSON.stringify(YOUR_RECEIPT_HERE);
const options = {
hostname: 'us.api.concursolutions.com',
path: `/receipts/v4/users/${USER_ID}`,
method: 'POST',
headers: {
'Authorization': `Bearer ${ACCESS_TOKEN}`,
'Content-Type': 'application/json',
'Content-Length': Buffer.byteLength(receipt),
'Link': '<http://schema.concursolutions.com/general-receipt.schema.json>;rel=describedBy'
}
};
const req = https.request(options, (res) => {
console.log('statusCode:', res.statusCode);
console.log('headers:', res.headers);
res.on('data', (data) => {
process.stdout.write(data);
});
});
req.write(receipt);
req.end();
req.on('error', (e) => {
console.error(e);
});
Endpoints
Definitions of Resources
- E-Receipt - A schema-enforced resource with data and, optionally, an image. If an image is not provided, one will be generated from the data resource.
- Image-Only Receipt - A standalone image without data.
Note: The Receipts V4 API only provides GET access to individual or user’s receipts that have been submitted through this API, and, therefore the response will not be comprehensive of every user receipt within SAP Concur. All other images should be obtained via the Image v1 API. Additionally, only the receipts will be returned, there will not be any corresponding entry data. Examples of Enterprise apps that should use the Image v1 API include: ERP integrations for financial journal entry postings, VAT reclaim integrations that obtain transactions to calculate VAT reclaim, project billing integrations used to substantiate expenses billed back, etc.
Supported Image Formats
- Image size must not exceed 25MB.
- Images with any dimension exceeding 2,200 pixels will be reduced, with the longest dimension reduced to 2,200 pixels and the remaining dimensions scaled down using a fixed aspect ratio.
- Image must be one of the supported file types: image/png, image/jpg, image/jpeg, image/tiff, image/tif, image/gif, and application/pdf. Images provided in image/tiff and image/tif will be converted to a PDF document with the image embedded within.
Endpoints - General
| Endpoint | Response Format | Request Summary |
|---|---|---|
| GET / | JSON | Get service index URLs |
| GET /v4/status/:receiptId | JSON | Get the status of a receipt |
Endpoint: Service Index
GET /
Making a GET request to the root of the service will return a list of current endpoints. If endpoint URLs ever change, the service index will be updated. To ensure that you are using the correct URLs, the safest practice is to check the service index before every request. The response will include current URLs for all endpoints in the receipt service.
Example Requests:
cURL:
curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/
HTTPie:
http https://us.api.concursolutions.com/receipts/ 'Authorization:Bearer {YOUR ACCESS TOKEN}'
Example Response:
{
"links": [
{
"rel": "self",
"href": "https://us.api.concursolutions.com/receipts/v4"
},
{
"rel": "receipt-get",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/v4/{receiptId}"
},
{
"rel": "receipt-post",
"method": "POST",
"href": "https://us.api.concursolutions.com/receipts/v4/users/{userId}"
},
{
"rel": "receipts-get-user",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/v4/users/{userId}"
},
{
"rel": "schemas-get",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas"
}
]
}
E-Receipts
| Endpoint | Response Format | Request Summary |
|---|---|---|
| GET /schemas | JSON | Get currently supported receipt schemas |
| POST /v4/users/:userId | N/A | Post a receipt |
| GET /v4/users/:userId | JSON | Get a user's receipts |
| GET /v4/:receiptId | JSON | Get a receipt by ID |
| GET /v4/:receiptId/image | image file | Get a receipt image. |
Endpoint: Schemas
GET /schemas/:schemaId
| Parameter | Requirement | Value |
|---|---|---|
| schemaId | optional | The ID of the schema to be returned. |
The response to a GET request to /schemas will have a list of JSON validation schemas for available receipt types. An array of supportingSchemas is also returned, but these do not represent actual receipt types.
If a schema ID is provided, then only the schema with that ID will be returned, instead of the entire schema index. The ID's of schemas are not UUIDs, but are instead just the names of the schema with the extension .schema.json. For example, car-rental-receipt.schema.json or air-receipt.schema.json.
One of the receipt schemas must be included in the link header of receipt POST requests with the relationship of describedBy. This looks like link: <http://schema.concursolutions.com/{RECEIPT TYPE}.schema.json>;rel=describedBy.
Example Requests:
cURL for the schema index:
curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/schemas/
HTTPie for the schema index:
http https://us.api.concursolutions.com/receipts/schemas 'Authorization:Bearer {YOUR ACCESS TOKEN}'
cURL for a single schema:
curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/schemas/car-rental-receipt.schema.json
HTTPie for a single schema:
http https://us.api.concursolutions.com/receipts/schemas/car-rental-receipt.schema.json 'Authorization:Bearer {YOUR ACCESS TOKEN}'
Example Response:
{
"receiptSchemas": [
{
"rel": "http://schema.concursolutions.com/air-receipt.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/air-receipt.schema.json"
},
{
"rel": "http://schema.concursolutions.com/car-rental-receipt.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/car-rental-receipt.schema.json"
},
{
"rel": "http://schema.concursolutions.com/general-receipt.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/general-receipt.schema.json"
},
{
"rel": "http://schema.concursolutions.com/ground-transport-receipt.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/ground-transport-receipt.schema.json"
},
{
"rel": "http://schema.concursolutions.com/hotel-receipt.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/hotel-receipt.schema.json"
},
{
"rel": "http://schema.concursolutions.com/jpt-ic-card-receipt.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/jpt-ic-card-receipt.schema.json"
},
{
"rel": "http://schema.concursolutions.com/rail-receipt.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/rail-receipt.schema.json"
}
],
"supportingSchemas": [
{
"rel": "http://schema.concursolutions.com/address-original.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/address-original.schema.json"
},
{
"rel": "http://schema.concursolutions.com/address.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/address.schema.json"
},
{
"rel": "http://schema.concursolutions.com/common.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/common.schema.json"
},
{
"rel": "http://schema.concursolutions.com/discount.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/discount.schema.json"
},
{
"rel": "http://schema.concursolutions.com/line-item.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/line-item.schema.json"
},
{
"rel": "http://schema.concursolutions.com/location.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/location.schema.json"
},
{
"rel": "http://schema.concursolutions.com/merchant.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/merchant.schema.json"
},
{
"rel": "http://schema.concursolutions.com/payments.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/payments.schema.json"
},
{
"rel": "http://schema.concursolutions.com/receipt-core.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/receipt-core.schema.json"
},
{
"rel": "http://schema.concursolutions.com/taxes.schema.json",
"method": "GET",
"href": "https://us.api.concursolutions.com/receipts/schemas/taxes.schema.json"
}
]
}
Endpoint: Get Receipt Status
GET /v4/status/:receiptId
| Parameter | Requirement | Value |
|---|---|---|
| receiptId | required | The id of the receipt associated with the image. |
This endpoint may be used to see the current processing status of a receipt.
When a successful POST request is made the Link header of the response contains a 'processing-status' URL. This processing-status URL will be available for two weeks after the initial POST and will provide information regarding the processing status of your receipt.
There are four possible top level statuses: ACCEPTED, FAILED, PROCESSING, and PROCESSED.
In additional to a high level status, information will be provided in an array of event logs. Events that may be included in the logs will be typed as INFO, DEBUG, WARNING, or ERROR.
Example event messages:
| Type | Message |
|---|---|
| INFO | Receipt accepted. Queued for processing. |
| INFO | Initiated receipt processing. (event for each attempt) |
| ERROR | Error from User Profile service. Queued for reprocessing. |
| ERROR | Error from Imaging service. Queued for reprocessing. |
| ERROR | Error during image generation or retrieval. Queued for reprocessing. |
| INFO | Receipt image generated. |
| ERROR | Processing failed. |
| INFO | Processing finished. |
Example Requests:
cURL:
curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/status/{RECEIPT ID}
HTTPie:
http https://us.api.concursolutions.com/receipts/v4/status/{RECEIPT ID} "Authorization: Bearer {YOUR ACCESS TOKEN}"
Example Response:
{
"status": "PROCESSED",
"logs": [
{
"logLevel": "INFO",
"message": "Receipt accepted. Queued for processing.",
"timestamp": "Mon, 08 May 2017 23:05:52 GMT"
},
{
"logLevel": "INFO",
"message": "Initiated receipt processing.",
"timestamp": "Mon, 08 May 2017 23:05:52 GMT"
},
{
"logLevel": "INFO",
"message": "Receipt image generated.",
"timestamp": "Mon, 08 May 2017 23:05:53 GMT"
},
{
"logLevel": "INFO",
"message": "Processing finished.",
"timestamp": "Mon, 08 May 2017 23:05:54 GMT"
}
]
}
Endpoint: Post a Receipt
POST /v4/users/:userId
| Parameter | Requirement | Value |
|---|---|---|
| userId | required | The id of the user to whom the receipt belongs. |
| receipt | required | The JSON receipt to be posted. |
| image | optional | Image of the receipt. If an image isn't provided, one will be generated automatically from the JSON. Refer to Supported Image Formats for more information. |
Creating a receipt requires JSON data about the transaction and, optionally, an image of the receipt. If an image is not supplied with the request, SAP Concur will automatically generate a receipt image based on the data provided. JSON schemas are used to validate the format of receipt data received in POST requests.
Successful POST requests will receive a response of 201 Created. The Location header of the response contains a URL for your receipt. Once the receipt has been processed, it can be retrieved at this URL. The Link header of the response contains a processing-status URL for your receipt. More information can be found here.
Helpful Notes:
- Include link as a header and make its value: “
If you are not providing an image with your receipt data, the body of the request should be your receipt JSON.
Receipt images may be posted along with data. In this case, SAP Concur will use the provided image instead of generating a new one. To post data and an image, use multipart form data. The Content-Type:multipart/form-data header must be set. The image should be included under the key image, and the receipt JSON should be included under the key receipt. For information regarding image size, dimension, and type, please refer to Supported Image Formats.
Example Requests:
cURL data without image:
curl -v -X POST https://us.api.concursolutions.com/receipts/v4/users/{USER ID FROM YOUR ID TOKEN} \
-H "Authorization: Bearer {YOUR ACCESS TOKEN}" \
-H "Content-Type: application/json" \
-H "link: <http://schema.concursolutions.com/{VALIDATION SCHEMA FROM SCHEMA ENDPOINT}.schema.json>;rel=describedBy" \
-d @{PATH TO YOUR RECEIPT JSON}
cURL data and image:
curl -v -k -X POST https://us.api.concursolutions.com/receipts/v4/users/{USER ID FROM YOUR ID TOKEN} \
-H "Authorization: Bearer {YOUR ACCESS TOKEN}" \
-H "Content-Type:multipart/form-data" \
-H "link: <http://schema.concursolutions.com/{VALIDATION SCHEMA FROM SCHEMA ENDPOINT}.schema.json>;rel=describedBy" \
-F "receipt=<{PATH TO YOUR RECEIPT JSON};type=application/json" \
-F "image=@{PATH TO YOUR IMAGE};type={FILE MIME TYPE OF YOUR IMAGE}"
HTTPie data without image:
http POST https://us.api.concursolutions.com/receipts/v4/users/{USER ID FROM YOUR ID TOKEN} \
"Authorization:Bearer {YOUR ACCESS TOKEN}" \
"Content-Type: application/json" \
"link: <http://schema.concursolutions.com/{VALIDATION SCHEMA FROM SCHEMA ENDPOINT}.schema.json>;rel=describedBy" \
< {PATH TO YOUR RECEIPT JSON}
Example Response:
HTTP/1.1 201 Created
Link: <http://schema.concursolutions.com/car-rental-receipt.schema.json>; rel="describedBy", <https://us.api.concursolutions.com/receipts/v4/status/b0a4ab2bce8a49a08cf177cb997bf2ee>; rel="processing-status"
Location: https://us.api.concursolutions.com/receipts/v4/b0a4ab2bce8a49a08cf177cb997bf2ee
Content-Length: 0
Connection: keep-alive
Endpoint: Get a Receipt by ID
GET /v4/:receiptId
| Parameter | Requirement | Value |
|---|---|---|
| receiptId | required | The id of the receipt to be returned. |
Returns the JSON receipt associated with the ID in the URL.
Example Requests:
cURL:
curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/{RECEIPT ID}
HTTPie:
http https://us.api.concursolutions.com/receipts/v4/{RECEIPT ID} "Authorization: Bearer {YOUR ACCESS TOKEN}"
Example Response
{
"dateTimeReceived": "2016-09-28T21:41:21.087Z",
"id": "85b76a2bf51a4ed7b8b252994d7d9e2b",
"image": "",
"receipt": {
...Receipt JSON...
},
"userId": "08bdda1e-0d4f-4261-9f1b-f9b8d9f817d6",
"validationSchema": "http://schema.concursolutions.com/car-rental-receipt.schema.json",
"self": "https://us.api.concursolutions.com/receipts/v4/85b76a2bf51a4ed7b8b252994d7d9e2b",
"template": "https://us.api.concursolutions.com/receipts/v4/{receiptId}"
}
Endpoint: Get Receipts By UserId
GET /v4/users/:userId
| Parameter | Requirement | Value |
|---|---|---|
| userId | required | The id of the user whose receipts will be returned. |
Returns all receipts for a given user ID.
Example Requests:
cURL:
curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/users/{USER ID}
HTTPie:
http https://us.api.concursolutions.com/receipts/v4/users/{USER ID} "Authorization: Bearer {YOUR ACCESS TOKEN}"
Example Response:
{
"receipts": [
{
"dateTimeReceived": "2016-09-28T21:41:21.087Z",
"id": "85b76a2bf51a4ed7b8b252994d7d9e2b",
"image": "",
"receipt": {
...Receipt JSON...
},
"userId": "08bdda1e-0d4f-4261-9f1b-f9b8d9f817d6",
"validationSchema": "http://schema.concursolutions.com/car-rental-receipt.schema.json",
"self": "https://us.api.concursolutions.com/receipts/v4/85b76a2bf51a4ed7b8b252994d7d9e2b",
"template": "https://us.api.concursolutions.com/receipts/v4/{receiptId}"
},
{
"dateTimeReceived": "2016-09-28T19:59:30.488Z",
"id": "df8c1161d917439c9e6f141fd0d6b588",
"image": "",
"receipt": {
...Receipt JSON...
},
"userId": "08bdda1e-0d4f-4261-9f1b-f9b8d9f817d6",
"validationSchema": "http://schema.concursolutions.com/car-rental-receipt.schema.json",
"self": "https://us.api.concursolutions.com/receipts/v4/df8c1161d917439c9e6f141fd0d6b588",
"template": "https://us.api.concursolutions.com/receipts/v4/{receiptId}"
},
...
]
}
Endpoint: Get Receipt Image
GET /v4/:receiptId/image
| Parameter | Requirement | Value |
|---|---|---|
| receiptId | required | The id of the receipt associated with the image. |
If an image or PDF document was generated by or POSTed to Receipts v4, this endpoint can return the image in the same format that it was originally received by the API. Images for receipts created with v3 of the API are not accessible via this endpoint.
Example Requests:
cURL:
curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/{RECEIPT ID}/image
HTTPie:
http https://us.api.concursolutions.com/receipts/v4/{RECEIPT ID}/image "Authorization: Bearer {YOUR ACCESS TOKEN}"
Image-Only Receipts
Note: This API is not designed to obtain the receipt images attached to an expense report. If you are an Enterprise Partner creating integrations that are intended to obtain final-approved Expense or Invoice data, and the accompanying receipt images that substantiate those transactions you will need to use Image v1. These scenarios include, but are not limited to: ERP integrations for financial journal entry postings, VAT reclaim integrations that obtain transactions to calculate VAT reclaim, project billing integrations used to substantiate expenses billed back, etc.
| Endpoint | Response Format | Request Summary |
|---|---|---|
| POST /v4/users/:userId/image-only-receipts | N/A | Post an image-only receipt |
| GET /v4/users/:userId/image-only-receipts | JSON | Get a user's image-only receipts |
| GET /v4/image-only-receipts/:receiptId | JSON | Get an image-only receipt by ID |
Endpoint: Post an Image-Only Receipt
POST /v4/users/:userId/image-only-receipts
| Parameter | Requirement | Value |
|---|---|---|
| userId | required | The id of the user to whom the receipt image belongs. |
| image | required | Image of the receipt. Refer to Supported Image Formats for more information. |
Successful POST requests will receive a response of 202 Accepted. The Location header of the response contains a URL for your receipt image. Once the receipt has been processed, it can be retrieved at this URL. The Link header of the response contains a processing-status URL for your receipt image.
Helpful Notes: - The header must include content-type with multipart/form-data as its value - In the body, add "image" as a key and select "file" from the dropdown since you will be linking an image file. Then, choose your saved image file as the value.
For information regarding image size, dimension, and type, please refer to Supported Image Formats.
Example Requests:
cURL:
curl -v -X POST https://us.api.concursolutions.com/receipts/v4/users/{USER ID FROM YOUR ID TOKEN}/image-only-receipts \
-H "Authorization: Bearer {YOUR ACCESS TOKEN}" \
-H "Content-Type:multipart/form-data" \
-F "image=@{PATH TO YOUR IMAGE};type=image/{FILE MIME TYPE OF YOUR IMAGE}"
Example Response:
HTTP/1.1 202 Accepted
Link: <https://us.api.concursolutions.com/receipts/v4/status/b0a4ab2bce8a49a08cf177cb997bf2ee>; rel="processing-status"
Location: https://us.api.concursolutions.com/receipts/v4/images/b0a4ab2bce8a49a08cf177cb997bf2ee
Content-Length: 0
Connection: keep-alive
Endpoint: Get Image-Only Receipts By UserId
GET /v4/users/:userId/image-only-receipts
| Parameter | Requirement | Value |
|---|---|---|
| userId | required | The id of the user whose receipt images will be returned. |
Returns the JSON metadata of receipt images for the user ID specified in the URL. Results should be paginated in the same manner as the e-receipt endpoint.
Example Requests:
cURL:
curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/users/{USER ID}/image-only-receipts
HTTPie:
http https://us.api.concursolutions.com/receipts/v4/users/{USER ID}/image-only-receipts "Authorization: Bearer {YOUR ACCESS TOKEN}"
Example Response:
HTTP/1.1 200 OK
Content-Length: 800
Connection: keep-alive
{
"receiptsImages": [
{
"dateTimeReceived": "Wed May 24 2017 16:14:17 GMT+00:00",
"id": "a90fc48e0f0a44f2bd4838fd773b07a5",
"image": "https://us.api.concursolutions.com/receipts/v4/image-only-receipts/a90fc48e0f0a44f2bd4838fd773b07a5/image",
"userId": "abcd123456efg"
},
{ ... },
],
"next": "https://us.api.concursolutions.com/receipts/v4/users/abcd123456efg/image-only-receipts/page/1507587575592_d4721b2f3b304a9a9325fabdad5f50ad"
}
Endpoint: Get an Image-Only Receipt by ID
GET /v4/image-only-receipts/:receiptId
| Parameter | Requirement | Value |
|---|---|---|
| receiptId | required | The id of the receipt image to be returned. |
Returns the JSON metadata associated with the ID in the URL.
Example Requests:
cURL:
curl -v -X GET https://us.api.concursolutions.com/receipts/v4/image-only-receipts/{RECEIPT ID} \
-H "Authorization: Bearer {YOUR ACCESS TOKEN}"
HTTPie:
http https://us.api.concursolutions.com/receipts/v4/image-only-receipts/{RECEIPT ID} "Authorization: Bearer {YOUR ACCESS TOKEN}"
Example Response
HTTP/1.1 200 OK
Content-Length: 272
Connection: keep-alive
{
"dateTimeReceived": "Wed May 24 2017 16:14:17 GMT+00:00",
"id": "a90fc48e0f0a44f2bd4838fd773b07a5",
"image": "https://us.api.concursolutions.com/receipts/v4/image-only-receipts/a90fc48e0f0a44f2bd4838fd773b07a5/image",
"userId": "abcd123456efg"
}
Endpoint: Get Receipt Image (Image-Only)
GET /v4/image-only-receipts/:receiptId/image
| Parameter | Requirement | Value |
|---|---|---|
| receiptId | required | The id of the receipt image to be returned. |
Returns the image in the same format that it was originally received by the API (image/png, image/jpg, image/jpeg, image/tiff, image/tif, image/gif, or application/pdf).
Example Requests:
cURL:
curl -H "Authorization: Bearer {YOUR ACCESS TOKEN}" https://us.api.concursolutions.com/receipts/v4/image-only-receipts/{RECEIPT ID}/image
HTTPie:
http https://us.api.concursolutions.com/receipts/v4/image-only-receipts/{RECEIPT ID}/image "Authorization: Bearer {YOUR ACCESS TOKEN}"
Supported Receipt Types
Receipts can be any of the following types
See the schema documentation below for the specifications of each type, plus the various schemas that are shared components of each receipt schema. Property names mentioned in bold italics are required fields.
Schemas
Address
| Property Name | Type | Format | Description |
|---|---|---|---|
| streetAddress | string | N/A | |
| addressLocality | string | N/A | City |
| addressRegion | string | ^[a-zA-Z0-9]{1,3}$ | 1 to 3 character country subdivision code as defined in ISO 3166-2:2013 |
| addressCountry | string | country-code | 2 or 3 character country code as defined in ISO 3166-1:2013 |
| postalCode | string | N/A |
Air Receipt
Schema for airline receipts. * Includes all of Receipt Core Definitions
| Property Name | Type | Format | Description |
|---|---|---|---|
| itineraryLocator | string | ^(?!\s*$).+ | Unique ID of an itinerary (also know as a trip) in Concur’s Itinerary Service. An itinerary can contain one or more bookings from various sources. |
| tickets | array | tickets | Air tickets issued. |
| lineItems | array | lineItems | Ancillary airline fees. |
tickets
| Property Name | Type | Format | Description |
|---|---|---|---|
| number | string | N/A | Ticket number issued by the airline when the payment is made. Ticket numbers are globally unique for all IATA carriers. The first 3 digits identify the airline. The three digit code for each airline can be found here. For example the ticket number for American Airlines where 001 is the airline: 0012375432602. |
| recordLocator | string | N/A | Confirmation identifier for the ticket created by the airline. For most airlines this is a 6 character alphanumeric code that is unique for a short period of time and could be reused in the future. |
| issueDateTime | string | date-time | Date and time the ticket was issued. |
| pseudoCityCode | string | ^[a-zA-Z]{3}$ | IATA city code the ticket was issued from. For example, SEA for Seattle. |
| IATAAgencyNumber | string | ^[0-9]{8}$ | Identifying number assigned by the IATA to the agency issuing the ticket. |
| agencyName | string | N/A | Name of the agency issuing the ticket. |
| passengerName | string | N/A | Name of the passenger associated with the ticket. |
| coupons | array | coupons | Flights issued within this transaction. |
coupons
| Property Name | Type | Format | Description |
|---|---|---|---|
| originationAirportIATACode | string | ^[a-zA-Z]{3}$ | IATA airport code of the flight’s origin. |
| originationDateTime | string | date-time | Date and time of origin. |
| destinationAirportIATACode | string | ^[a-zA-Z]{3}$ | IATA airport code of the flight’s destination. |
| destinationDateTime | string | date-time | Date and time of destination. |
| flightNumber | string | N/A | Flight identifier. |
| couponNumber | string | ^(?!\s*$).+ | Identifier associated with the given coupon. |
| operatingAirlineCode | string | ^[a-zA-Z]{2}$ | IATA code of the airline operating the flight. |
| marketingCarrier | string | ^[a-zA-Z0-9]{3,8}$ | Flight designator booking the flight. |
| operatingCarrier | string | ^[a-zA-Z0-9]{3,8}$ | Flight designator operating the flight. |
| classOfServiceCode | string | ^[a-zA-Z]$ | Class of service per the airline’s class of service codes. Most airlines use the same codes but some airlines have custom codes. |
| fareBasisCode | string | ^[a-zA-Z0-9]{2,8}$ | Rate code the airline used to calculate the fare for this flight. |
| ticketDesignatorCode | string | ^[a-zA-Z0-9*?]{1,10}$ | A valid ticket designator code to indicate what type of discount is applied, such as for a child or infant, or airline employee. This is a 1 to 10 alphanumeric code and can optionally include a single asterisk. Ticket designators are free-form text codes which help identify ticket types. Airlines determine which ticket designators they will use as no standards currently exist. |
| fare | string | ^[-]?\d*.?\d+$ | Fare charged for the flight. |
| taxes | array | Taxes | Schema for objects that make up an array of taxes. Used in most receipt types. |
| lineItems | array | lineItems | Line Items/fees specific to a leg of the trip. Eg. Baggage fees, class of service fees, priority boarding, meals. |
Definitions
| Property Name | Type | Format | Description |
|---|---|---|---|
| IATAAirportCode | string | ^[a-zA-Z]{3}$ | 3-letter IATA code for an airport. |
| IATAAirlineCode | string | ^[a-zA-Z]{2}$ | 2-letter code for an airline. |
| IATACityCode | string | ^[a-zA-Z]{3}$ | 3-letter IATA city code. For example, SEA for Seattle. |
| IATAAgencyNumber | string | ^[0-9]{8}$ | 8-character ID number assigned by the IATA to an agency. |
| flightDesignator | string | ^[a-zA-Z0-9]{3,8}$ | |
| classOfServiceCode | string | ^[a-zA-Z]$ | |
| fareBasisCode | string | ^[a-zA-Z0-9]{2,8}$ | |
| ticketDesignatorCode | string | ^[a-zA-Z0-9*?]{1,10}$ |
Car Rental Receipt
Schema for car rentals. This does not include ride services or taxis. * Includes all of Receipt Core Definitions
| Property Name | Type | Format | Description |
|---|---|---|---|
| itineraryLocator | string | ^(?!\s*$).+ | Unique ID of an itinerary (also know as a trip) in Concur’s Itinerary Service. An itinerary can contain one or more bookings from various sources. |
| segmentLocator | string | ^(?!\s*$).+ | Unique ID of a single travel event in Concur’s Itinerary Service. An itinerary can contain one or more bookings and each booking can contain one or more segments. The segmentLocator uniquely identifies an event like a car rental with a specific start and end date or a single air segment/sector. |
| startDateTime | string | date-time | A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time. |
| endDateTime | string | date-time | A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time. |
| pickupLocation | object | Location | Schema representing a location, including geographical information and a postal address. Used in multiple receipt types. |
| dropoffLocation | object | Location | Schema representing a location, including geographical information and a postal address. Used in multiple receipt types. |
| rentalDays | integer | N/A | Total number of days for which the car was rented. |
| rentalAgreementNumber | string | N/A | Agreement identifier. |
| confirmationNumber | string | N/A | Booking confirmation identifier. |
| vehicle | object | vehicle | |
| driverName | string | N/A | Name of the driver/renter of the vehicle. |
| distance | object | distance | Distance traveled. |
| odometerReadingOut | number | N/A | Odometer reading at the start of the rental period. A number with up to one decimal place is expected. |
| odometerReadingIn | number | N/A | Odometer reading at the end of the rental period. A number with up to one decimal place is expected. |
| additionalDriver | boolean | N/A | Additional approved driver (true) or not (false). |
| lineItems | array | lineItems | Break down of all car rental charges. This could include daily rate, fees, insurance, GPS rental and other add-ons. |
vehicle
| Property Name | Type | Format | Description |
|---|---|---|---|
| registrationNumber | string | N/A | Registration or license plate identifier. |
| description | string | N/A | Vehicle description, including year, make and model. |
| classReservedCode | string | ^[a-zA-Z]{4}$ | Four-letter Association of Car Rental Industry Systems Standard (ACRISS) car code. |
| classRentedCode | string | ^[a-zA-Z]{4}$ | Actual vehicle rented ACRISS identifier. |
| classChargedCode | string | ^[a-zA-Z]{4}$ | Car class code actually charged to the user. |
| engineSize | string | ^[0-9]{1,4}$ | Engine displacement in cubic centimeters. |
Definitions
| Property Name | Type | Format | Description |
|---|---|---|---|
| acrissCarCode | string | ^[a-zA-Z]{4}$ | Four-letter Association of Car Rental Industry Systems Standard (ACRISS) car code. |
| engineSize | string | ^[0-9]{1,4}$ | Engine displacement in cubic centimeters. |
Common Definitions
Shared definitions that are utilized in multiple receipt types.
Definitions
| Property Name | Type | Format | Description |
|---|---|---|---|
| dateTime | string | date-time | The dateTime validation validates for a subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; This is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time. |
| duration | string | ^(-)?P(?:(-?[0-9,.])Y)?(?:(-?[0-9,.])M)?(?:(-?[0-9,.])W)?(?:(-?[0-9,.])D)?(?:T(?:(-?[0-9,.])H)?(?:(-?[0-9,.])M)?(?:(-?[0-9,.]*)S)?)?$ | Duration of a time interval as defined in ISO 8601 |
| nonEmptyString | string | ^(?!\s*$).+ | Non-empty string. Length must be at least 1 character. |
| addressRegion | string | ^[a-zA-Z0-9]{1,3}$ | 1 to 3 character country subdivision code as defined in ISO 3166-2:2013 |
| addressCountry | string | country-code | 2 or 3 character country code as defined in ISO 3166-1:2013 |
| currency | string | ^[-]?\d*.?\d+$ | String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
| currencyCode | string | currency-code | 3-letter currency code as defined in ISO 4217 |
| latitude | number | N/A | Numeric latitude value between -90 and 90 |
| longitude | number | N/A | Numeric longitude value between -180 and 180 |
| positiveInteger | integer | N/A | Positive integer value of at least 1 |
| positiveNumber | number | N/A | Positive number value of at least 0 |
| negativeCurrency | string | ^[-]\d*.?\d+$ | String representing a negative amount of money, normally used for a discount. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
distance
| Property Name | Type | Format | Description |
|---|---|---|---|
| totalDistance | number | N/A | |
| unit | N/A | N/A | Can be any of the following values: mi, km |
Discount
Schema for discounts, such as coupons or discount codes, that could be part of a transaction.
| Property Name | Type | Format | Description |
|---|---|---|---|
| discountName | string | N/A | The name of the discount. |
| discountCode | string | N/A | The code for the discount. |
| discountRate | string | N/A | The percentage of discount provided. |
| discountAmount | string | ^[-]\d*.?\d+$ | String representing a negative amount of money, normally used for a discount. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
General Receipt
General receipt type for transactions that do not fall under one of the more specific receipt types. This might include retail stores or restaurants. * Includes all of Receipt Core Definitions
| Property Name | Type | Format | Description |
|---|---|---|---|
| lineItems | array | lineItems | Line items specified for general receipts. |
Ground Transport Receipt
Schema for ground transportation receipts. This includes essentially all forms of non-aerial transportation, except those that run on railed tracks. * Includes all of Receipt Core Definitions
| Property Name | Type | Format | Description |
|---|---|---|---|
| itineraryLocator | string | ^(?!\s*$).+ | Non-empty string. Length must be at least 1 character. |
| segmentLocator | string | ^(?!\s*$).+ | Non-empty string. Length must be at least 1 character. |
| classOfService | string | ^(?!\s*$).+ | Non-empty string. Length must be at least 1 character. |
| startDateTime | string | date-time | A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time. |
| endDateTime | string | date-time | A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time. |
| travelDuration | string | ^(-)?P(?:(-?[0-9,.])Y)?(?:(-?[0-9,.])M)?(?:(-?[0-9,.])W)?(?:(-?[0-9,.])D)?(?:T(?:(-?[0-9,.])H)?(?:(-?[0-9,.])M)?(?:(-?[0-9,.]*)S)?)?$ | Duration of a time interval as defined in ISO 8601 |
| mapUrl | string | Google Maps URI Pattern | Link to an image of the traveled route. |
| pickupLocation | object | Location | Schema representing a location, including geographical information and a postal address. Used in multiple receipt types. |
| dropoffLocation | object | Location | Schema representing a location, including geographical information and a postal address. Used in multiple receipt types. |
| distance | object | distance | Object representing a distance. |
| driverNumber | string | N/A | Unique identifier assigned by the ride company to a driver. |
| lineItems | array | lineItems | Descriptive breakdown of the fare charged. For example: base fare, distance travelled, discount and other add-ons. |
Google Maps URI Pattern: ^https://(www|maps).(googleapis|google).[a-z]+/maps/
Hotel Receipt
Schema for hotel receipts. * Includes all of Receipt Core Definitions
| Property Name | Type | Format | Description |
|---|---|---|---|
| itineraryLocator | string | ^(?!\s*$).+ | Unique ID of an itinerary (also know as a trip) in Concur’s Itinerary Service. An itinerary can contain one or more bookings from various sources. |
| segmentLocator | string | ^(?!\s*$).+ | Unique ID of a single travel event in Concur’s Itinerary Service. An itinerary can contain one or more bookings and each booking can contain one or more segments. The segmentLocator uniquely identifies an event like a car rental with a specific start and end date or a single air segment/sector. |
| property | object | Location | Physical property location information for the hotel property. This is often different than the merchant location information. |
| confirmationNumber | string | N/A | Booking identifier. |
| checkInDateTime | string | date-time | A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time. |
| checkOutDateTime | string | date-time | A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time. |
| guests | array | guests | Guest information. |
| numberInParty | integer | N/A | Number of individuals for the stay. |
| room | object | room | |
| nightsStayed | integer | N/A | Positive integer value of at least 1 |
| lineItems | array | lineItems |
guests
| Property Name | Type | Format | Description |
|---|---|---|---|
| guestNameRecord | string | N/A | The loyalty or membership number of the hotel guest. |
| firstName | string | ^(?!\s*$).+ | Non-empty string. Length must be at least 1 character. |
| lastName | string | ^(?!\s*$).+ | Non-empty string. Length must be at least 1 character. |
| address | object | Address | Address of the guest. It is highly recommended that the business address of the guest is provided if the hotel is provided with one. Doing so will help VAT reclamation partners who work with companies, to have compliant receipts accepted by the tax authority when filing tax reclaims. |
property
| Property Name | Type | Format | Description |
|---|---|---|---|
| name | string | N/A | The name for the location. |
| number | string | N/A | The identifier the company assigned to this location. |
| latitude | number | N/A | Numeric latitude value between -90 and 90 |
| longitude | number | N/A | Numeric longitude value between -180 and 180 |
| internetAddress | string | N/A | |
| emailAddress | string | N/A | |
| telephoneNumber | string | N/A | |
| faxNumber | string | N/A | |
| address | object | Address | Common address object used by all receipt types except for the JPT IC Card receipt, which uses Address-Original. |
room
| Property Name | Type | Format | Description |
|---|---|---|---|
| roomNumber | string | N/A | Room number where the guest stayed. |
| roomType | string | N/A | Type of room where the guest stayed. For example, Standard, Deluxe, etc. |
| ratePlanType | string | N/A | Name of the rate plan according to which the guest was charged. |
| averageDailyRoomRate | string | ^[-]?\d*.?\d+$ | Average of the daily room rates for the duration of the guests stay. Room rates usually differ from day to day. |
segments
| Property Name | Type | Format | Description |
|---|---|---|---|
| sequenceNumber | integer | N/A | Unique transaction identifier for every trip taken using the IC card. |
| dateTime | string | date-time | A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time. |
| fromStationCode | string | N/A | Departure station code of the route. This code is specified to the IC Card vendor. Concur Expense has a transcoding table to Expense location codes. |
| fromStationName | string | N/A | Departure station label of the route. |
| toStationCode | string | N/A | Arrival station code of the route. This code is specified to the IC Card vendor. Concur Expense has a transcoding table to Expense location codes. |
| toStationName | string | N/A | Arrival station label of the route. |
| fromIsCommuterPass | boolean | N/A | Whether or not the departure route is included in the commuter pass subscription of the employee. |
| toIsCommuterPass | boolean | N/A | Whether or not the arrival route is included in the commuter pass subscription of the employee. |
| distance | number | N/A | Positive number value of at least value as 0 |
icCardSegment
| Property Name | Type | Format | Description |
|---|---|---|---|
| sequenceNumber | integer | N/A | Unique transaction identifier for every trip taken using the IC card. |
| dateTime | string | date-time | Transaction date and time. |
| fromStationCode | string | N/A | Departure station code of the route. This code is specified to the IC Card vendor. Concur Expense has a transcoding table to Expense location codes. |
| fromStationName | string | N/A | Departure station label of the route. |
| toStationCode | string | N/A | Arrival station code of the route. This code is specified to the IC Card vendor. Concur Expense has a transcoding table to Expense location codes. |
| toStationName | string | N/A | Arrival station label of the route. |
| fromIsCommuterPass | boolean | N/A | Whether or not the departure route is included in the commuter pass subscription of the employee. |
| toIsCommuterPass | boolean | N/A | Whether or not the arrival route is included in the commuter pass subscription of the employee. |
| distance | number | N/A | Positive number value of at least value as 0 |
Line Item
Generic line item. These objects are included in arrays in most receipt types.
| Property Name | Type | Format | Description |
|---|---|---|---|
| sequenceNumber | integer | N/A | The order in which the item appears in the sequence of line items when the receipt is rendered by Concur. |
| dateTime | string | date-time | A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time. |
| reference | string | N/A | The item SKU, identifier or some other attribute the merchant uses to reference the item. |
| description | string | ^(?!\s*$).+ | Non-empty string. Length must be at least 1 character. |
| additionalDescription | string | N/A | |
| semanticsCode | string | ^(?!\s*$).+ | The Concur semantics code for the line item. |
| unitCost | string | ^[-]?\d*.?\d+$ | Amount per unit. |
| quantity | integer | N/A | |
| total | string | ^[-]?\d*.?\d+$ | String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
| subtotal | string | ^[-]?\d*.?\d+$ | String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
| taxesTotal | string | ^[-]?\d*.?\d+$ | String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
| taxes | array | Taxes | Schema for objects that make up an array of taxes. Used in most receipt types. |
| vatApplicable | boolean | N/A | If the line item was subject to a value added tax then true, if not then false. |
| amountIncludesVat | boolean | N/A | |
| discounts | array | discounts | The discounts offered for this line item. |
Location
Schema representing a location, including geographical information and a postal address. Used in multiple receipt types.
| Property Name | Type | Format | Description |
|---|---|---|---|
| name | string | N/A | The name for the location. |
| number | string | N/A | The identifier the company assigned to this location. |
| latitude | number | N/A | Numeric latitude value between -90 and 90 |
| longitude | number | N/A | Numeric longitude value between -180 and 180 |
| internetAddress | string | N/A | |
| emailAddress | string | N/A | |
| telephoneNumber | string | N/A | |
| faxNumber | string | N/A | |
| address | object | Address | Common address object used by all receipt types except for the JPT IC Card receipt, which uses Address-Original. |
Merchant
Schema for an object representing a merchant. The broker and seller properties in all receipts use this schema.
| Property Name | Type | Format | Description |
|---|---|---|---|
| name | string | ^(?!\s*$).+ | Non-empty string. Length must be at least 1 character. |
| description | string | N/A | Description of the service provided by the merchant. |
| taxId | string | N/A | The tax identification number assigned to the merchant by the national tax authority. If the partner is providing a tax invoice, then providing a tax identification number is recommended. |
| location | object | Location | Schema representing a location, including geographical information and a postal address. Used in multiple receipt types. |
Payments
The payments array allows for one or more payment methods used in the transaction to be defined. All payment methods defined within the array result in the value for total in the base object of the receipt. The JSON keyword ‘anyOf’ indicates at least one of the following is required and multiple can be present: cash, creditCard, companyPaid, digitalWallet and / or unusedTicket.
cash
| Property Name | Type | Format | Description |
|---|---|---|---|
| amount | string | ^[-]?\d*.?\d+$ | String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
creditCard
| Property Name | Type | Format | Description |
|---|---|---|---|
| amount | string | ^[-]?\d*.?\d+$ | String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
| cardDetail | object | cardDetail | Credit card information. |
cardDetail
| Property Name | Type | Format | Description |
|---|---|---|---|
| cardType | N/A | N/A | Can be any of the following values: American Express, Diners Club, Discover, MasterCard, Visa, Carte Blanche, Enroute, Universal Air Travel, JCB, EuroCard |
| creditCardId | string | ^[0-9]{4}$ | Last four digits of the credit card number to meet FACTA and PCI requirements |
| authorizationCode | string | N/A | Authorization code for transaction. |
companyPaid
| Property Name | Type | Format | Description |
|---|---|---|---|
| source | N/A | N/A | Can be any of the following values: GhostCard, LodgeCard, DirectPay, Invoice |
| amount | string | ^[-]?\d*.?\d+$ | String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
| cardDetail | object | cardDetail | Credit card information. |
cardDetail
| Property Name | Type | Format | Description |
|---|---|---|---|
| cardType | N/A | N/A | Can be any of the following values: American Express, Diners Club, Discover, MasterCard, Visa, Carte Blanche, Enroute, Universal Air Travel, JCB, EuroCard |
| creditCardId | string | ^[0-9]{4}$ | Last four digits of the credit card number to meet FACTA and PCI requirements |
| authorizationCode | string | N/A | Authorization code for transaction. |
digitalWallet
| Property Name | Type | Format | Description |
|---|---|---|---|
| source | N/A | N/A | Can be any of the following values: ApplePay, AndroidPay, SamsungPay, PayPal, OlaMoney |
| amount | string | ^[-]?\d*.?\d+$ | String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
unusedTicket
| Property Name | Type | Format | Description |
|---|---|---|---|
| ticketNumber | string | ^(?!\s*$).+ | Non-empty string. Length must be at least 1 character. |
| amount | string | ^[-]?\d*.?\d+$ | String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
cardDetail
| Property Name | Type | Format | Description |
|---|---|---|---|
| cardType | N/A | N/A | Can be any of the following values: American Express, Diners Club, Discover, MasterCard, Visa, Carte Blanche, Enroute, Universal Air Travel, JCB, EuroCard |
| creditCardId | string | ^[0-9]{4}$ | Last four digits of the credit card number to meet FACTA and PCI requirements |
| authorizationCode | string | N/A | Authorization code for transaction. |
Rail Receipt
Schema for rail or train receipts. * Includes all of Receipt Core Definitions
| Property Name | Type | Format | Description |
|---|---|---|---|
| itineraryLocator | string | ^(?!\s*$).+ | Unique ID of an itinerary (also know as a trip) in Concur’s Itinerary Service. An itinerary can contain one or more bookings from various sources. |
| lineItems | array | lineItems | Break down of all charges which could include insurance purchased for all train tickets, paid wi-fi etc. |
| railTickets | array | railTickets |
railTickets
| Property Name | Type | Format | Description |
|---|---|---|---|
| ticketNumber | string | N/A | |
| recordLocator | string | N/A | Confirmation identifier for the ticket. This code is usually unique for a short period of time and could be reused by the rail company in the future. |
| issueDateTime | string | date-time | Date and time the ticket was issued. |
| passengerName | string | N/A | Name of the person associated withthe ticket. |
| fare | string | ^[-]?\d*.?\d+$ | Fare charged for a train ticket. This will be the total of all segments in this train ticket. |
| segments | array | segments | Segments for this train ticket. |
segments
| Property Name | Type | Format | Description |
|---|---|---|---|
| departureStation | string | N/A | Name of the station from which the train is departing. |
| departureDateTime | string | date-time | A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time. |
| arrivalStation | string | N/A | Name of the station where the train is arriving. |
| arrivalDateTime | string | date-time | A subset of ISO 8601 date-times. The first restriction is that the dateTime requires a date, a time (at least the hour portion), and a UTC offset. The second restriction is that the dateTime does not allow a time to be formatted in UTC time (2015-11-02T14:30Z - notice the Z) without an offset; this is because it would be impossible for us to know the original offset so we could not generate a receipt with the correct local time. |
| trainNumber | string | N/A | Train identifier |
| trainType | string | N/A | Type of train. For example TGV or TER in France. |
| classOfServiceCode | string | ^(?!\s*$).+ | The class of travel. |
| fare | string | ^[-]?\d*.?\d+$ | Fare charged for this segment of the train ride. |
| taxes | array | Taxes | Taxes paid for this segment. |
| lineItems | array | lineItems | Line items specific to this segment. This could include meals, seat reservations, insurance etc. |
Receipt Core Definitions
Core values for all receipt types. All major receipt schemas include these core objects.
| Property Name | Type | Format | Description |
|---|---|---|---|
| dateTime | string | date-time | Date and time of the transaction. |
| total | string | ^[-]?\d*.?\d+$ | The total amount of the transaction including all lineitems and taxes. |
| subtotal | string | ^[-]?\d*.?\d+$ | The amount in the transaction excluding taxes. |
| taxesTotal | string | ^[-]?\d*.?\d+$ | The amount of tax paid in the transaction. |
| discountsTotal | string | ^[-]\d*.?\d+$ | String representing a negative amount of money, normally used for a discount. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
| currencyCode | string | currency-code | Currency paid to the merchant. |
| broker | object | Merchant | The entity that facilitates the transaction between the seller and end user. |
| seller | object | Merchant | The entity providing service to the end user. |
| payments | array | Payments | |
| discounts | array | discounts | The discounts offered on this transaction. |
| taxes | array | Taxes | Taxes paid as part of transaction. |
| reference | string | N/A | The unique receipt provider or merchant identifier for this receipt or invoice. This value can also be referred to as transaction number, check number, order ID or similar. |
| collectionReference | string | N/A | Use this key to group related receipts into a collection for credits, tips or other adjustments to the original transaction and looking at groups of receipts for analysis purposes. The reference and collectionReference keys typically have separate and unique values but could be the same for the first receipt in a collection. |
| taxInvoice | boolean | N/A | A tax invoice (true) or otherwise (false). |
broker
| Property Name | Type | Format | Description |
|---|---|---|---|
| name | string | ^(?!\s*$).+ | Non-empty string. Length must be at least 1 character. |
| description | string | N/A | Description of the service provided by the merchant. |
| taxId | string | N/A | The tax identification number assigned to the merchant by the national tax authority. If the partner is providing a tax invoice, then providing a tax identification number is recommended. |
| location | object | Location | Schema representing a location, including geographical information and a postal address. Used in multiple receipt types. |
seller
| Property Name | Type | Format | Description |
|---|---|---|---|
| name | string | ^(?!\s*$).+ | Non-empty string. Length must be at least 1 character. |
| description | string | N/A | Description of the service provided by the merchant. |
| taxId | string | N/A | The tax identification number assigned to the merchant by the national tax authority. If the partner is providing a tax invoice, then providing a tax identification number is recommended. |
| location | object | Location | Schema representing a location, including geographical information and a postal address. Used in multiple receipt types. |
Taxes
Schema for objects that make up an array of taxes. Used in most receipt types.
| Property Name | Type | Format | Description |
|---|---|---|---|
| authority | object | authority | The country or subdivision that charged the tax as per ISO 3166-2:2013. |
| name | string | N/A | |
| rate | number | N/A | |
| rateType | string | N/A | The rate type for the tax charged. For value added tax this could be Zero, Standard, Reduced, etc. |
| amount | string | ^[-]?\d*.?\d+$ | String representing an amount of money. Should not include a currency code or symbol, as this information is included in the currencyCode field of the receipt. |
authority
| Property Name | Type | Format | Description |
|---|---|---|---|
| addressCountry | string | country-code | 2 or 3 character country code as defined in ISO 3166-1:2013 |
| addressRegion | string | ^[a-zA-Z0-9]{1,3}$ | 1 to 3 character country subdivision code as defined in ISO 3166-2:2013 |
Sample Receipts
Below we have sample receipt data and the corresponding receipt images for the following receipt types:
Air (Multiple Tickets)
Receipt Data
{
"taxInvoice": true,
"reference": "ABCD1234",
"dateTime": "2099-11-10T16:04:49-0700",
"total": "1400.40",
"taxesTotal": "123.38",
"subtotal": "1277.02",
"currencyCode": "USD",
"broker": {
"name": "ACME Corporation",
"description": "",
"taxId": "123-21213",
"location": {
"name": "Headquarters",
"number": "",
"latitude": 41.8819,
"longitude": -87.6278,
"internetAddress": "http://www.acmecorporation.com",
"emailAddress": "info@acmecorporation.com",
"telephoneNumber": "1-877-555-5555",
"faxNumber": "",
"address": {
"streetAddress": "333 108th Ave NE",
"addressLocality": "Bellevue",
"addressRegion": "WA",
"addressCountry": "US",
"postalCode": "98004"
}
}
},
"seller": {
"name": "ACME Airlines",
"description": "",
"taxId": "867-53090",
"location": {
"name": "Headquarters",
"number": "",
"latitude": 37.2714,
"longitude": -85.3262,
"internetAddress": "http://www.acmeairlines.com",
"emailAddress": "contact@acmeairlines.com",
"telephoneNumber": "1-888-555-5555",
"faxNumber": "",
"address": {
"streetAddress": "1 Ground Transport Way",
"addressLocality": "Seattle",
"addressRegion": "WA",
"addressCountry": "US",
"postalCode": "90001"
}
}
},
"taxes": [
{
"authority": {
"addressCountry": "US",
"addressRegion": "WA"
},
"name": "Transportation Tax",
"rate": 7.50,
"amount": "91.38"
},
{
"authority": {
"addressCountry": "US"
},
"name": "United States - Flight Segment Tax",
"rate": 10.0,
"amount": "32.00"
}
],
"payments": [
{
"amount": "1400.40",
"cardDetail": {
"cardType": "Visa",
"creditCardId": "7423",
"authorizationCode": "AB123654789"
}
}
],
"itineraryLocator": "1122337694093",
"tickets": [
{
"number": "0062698215636",
"recordLocator": "CU9GEF",
"issueDateTime": "2015-11-29T19:15:55-0700",
"pseudoCityCode": "SEA",
"IATAAgencyNumber": "87654321",
"agencyName": "ACME Airlines",
"passengerName": "Jimmy Dean",
"fare": "609.31",
"coupons": [
{
"originationAirportIATACode": "SEA",
"originationDateTime": "2015-12-25T09:00:00-0700",
"destinationAirportIATACode": "MSP",
"destinationDateTime": "2015-12-25T14:14:00-0500",
"flightNumber": "DL 1768",
"couponNumber": "D167693",
"operatingAirlineCode": "DL",
"marketingCarrier": "DL1768",
"operatingCarrier": "DL1768",
"classOfServiceCode": "T",
"fareBasisCode": "YHRT15",
"ticketDesignatorCode": "FSG*SFR",
"fare": "152.33",
"taxes": [
{
"authority": {
"addressCountry": "US"
},
"name": "Transportation Tax",
"rate": 7.50,
"amount": "11.42"
}
],
"lineItems": [
{
"sequenceNumber": 1,
"description": "United States - September 11th Security Fee",
"additionalDescription": "Passenger Civil Aviation Security Service Fee",
"semanticsCode": "OTHER",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "2.80"
},
{
"sequenceNumber": 2,
"description": "United States - Passenger Facility Charge",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_FEE",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.50"
},
{
"sequenceNumber": 3,
"description": "United States - Flight Segment Tax",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_TAX",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.00"
}
]
},
{
"originationAirportIATACode": "MSP",
"originationDateTime": "2015-12-25T15:25:00-0500",
"destinationAirportIATACode": "GFK",
"destinationDateTime": "2015-12-25T16:50:00-0500",
"flightNumber": "OO 4656",
"couponNumber": "D187322",
"operatingAirlineCode": "DL",
"marketingCarrier": "DL1768Z",
"operatingCarrier": "OO4656B",
"classOfServiceCode": "T",
"fareBasisCode": "YAD1234",
"ticketDesignatorCode": "FSG*SFR",
"fare": "121.86",
"taxes": [
{
"authority": {
"addressCountry": "US"
},
"name": "Transportation Tax",
"rate": 7.50,
"amount": "9.14"
}
],
"lineItems": [
{
"sequenceNumber": 1,
"description": "United States - September 11th Security Fee",
"additionalDescription": "Passenger Civil Aviation Security Service Fee",
"semanticsCode": "OTHER",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "2.24"
},
{
"sequenceNumber": 2,
"description": "United States - Passenger Facility Charge",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_FEE",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "3.60"
},
{
"sequenceNumber": 3,
"description": "United States - Flight Segment Tax",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_TAX",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.00"
}
]
},
{
"originationAirportIATACode": "GFK",
"originationDateTime": "2015-12-30T17:19:00-0500",
"destinationAirportIATACode": "MSP",
"destinationDateTime": "2015-12-30T18:34:00-0500",
"flightNumber": "OO 4656",
"couponNumber": "D187322",
"operatingAirlineCode": "DL",
"marketingCarrier": "DL1768Z",
"operatingCarrier": "OO4656B",
"classOfServiceCode": "T",
"fareBasisCode": "YAD1234",
"ticketDesignatorCode": "FSG*SFR",
"fare": "140.14",
"taxes": [
{
"authority": {
"addressCountry": "US"
},
"name": "Transportation Tax",
"rate": 7.50,
"amount": "10.51"
}
],
"lineItems": [
{
"sequenceNumber": 1,
"description": "United States - September 11th Security Fee",
"additionalDescription": "Passenger Civil Aviation Security Service Fee",
"semanticsCode": "OTHER",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "2.58"
},
{
"sequenceNumber": 2,
"description": "United States - Passenger Facility Charge",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_FEE",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.14"
},
{
"sequenceNumber": 3,
"description": "United States - Flight Segment Tax",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_TAX",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.00"
}
]
},
{
"originationAirportIATACode": "MSP",
"originationDateTime": "2015-12-30T19:25:00-0500",
"destinationAirportIATACode": "SEA",
"destinationDateTime": "2015-12-30T21:15:00-0700",
"flightNumber": "DL 2536",
"couponNumber": "D187322",
"operatingAirlineCode": "DL",
"marketingCarrier": "DL2536Z",
"operatingCarrier": "DL2536B",
"classOfServiceCode": "T",
"fareBasisCode": "YAD1234",
"ticketDesignatorCode": "FSG*SFR",
"fare": "194.98",
"taxes": [
{
"authority": {
"addressCountry": "US"
},
"name": "Transportation Tax",
"rate": 7.50,
"amount": "14.62"
}
],
"lineItems": [
{
"sequenceNumber": 1,
"description": "United States - September 11th Security Fee",
"additionalDescription": "Passenger Civil Aviation Security Service Fee",
"semanticsCode": "OTHER",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "3.58"
},
{
"sequenceNumber": 2,
"description": "United States - Passenger Facility Charge",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_FEE",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "5.76"
},
{
"sequenceNumber": 3,
"description": "United States - Flight Segment Tax",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_TAX",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.00"
}
]
}
]
},
{
"number": "0062698215637",
"recordLocator": "CU9GEF",
"issueDateTime": "2015-11-29T19:15:55-0700",
"pseudoCityCode": "SEA",
"IATAAgencyNumber": "87654321",
"agencyName": "ACME Airlines",
"passengerName": "John Smith",
"fare": "609.31",
"coupons": [
{
"originationAirportIATACode": "SEA",
"originationDateTime": "2015-12-25T09:00:00-0700",
"destinationAirportIATACode": "MSP",
"destinationDateTime": "2015-12-25T14:14:00-0500",
"flightNumber": "DL 1768",
"couponNumber": "D167693",
"operatingAirlineCode": "DL",
"marketingCarrier": "DL1768",
"operatingCarrier": "DL1768",
"classOfServiceCode": "T",
"fareBasisCode": "YHRT15",
"ticketDesignatorCode": "FSG*SFR",
"fare": "152.33",
"taxes": [
{
"authority": {
"addressCountry": "US"
},
"name": "Transportation Tax",
"rate": 7.50,
"amount": "11.42"
}
],
"lineItems": [
{
"sequenceNumber": 1,
"description": "United States - September 11th Security Fee",
"additionalDescription": "Passenger Civil Aviation Security Service Fee",
"semanticsCode": "OTHER",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "2.80"
},
{
"sequenceNumber": 2,
"description": "United States - Passenger Facility Charge",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_FEE",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.50"
},
{
"sequenceNumber": 3,
"description": "United States - Flight Segment Tax",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_TAX",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.00"
}
]
},
{
"originationAirportIATACode": "MSP",
"originationDateTime": "2015-12-25T15:25:00-0500",
"destinationAirportIATACode": "GFK",
"destinationDateTime": "2015-12-25T16:50:00-0500",
"flightNumber": "OO 4656",
"couponNumber": "D187322",
"operatingAirlineCode": "DL",
"marketingCarrier": "DL1768Z",
"operatingCarrier": "OO4656B",
"classOfServiceCode": "T",
"fareBasisCode": "YAD1234",
"ticketDesignatorCode": "FSG*SFR",
"fare": "121.86",
"taxes": [
{
"authority": {
"addressCountry": "US"
},
"name": "Transportation Tax",
"rate": 7.50,
"amount": "9.14"
}
],
"lineItems": [
{
"sequenceNumber": 1,
"description": "United States - September 11th Security Fee",
"additionalDescription": "Passenger Civil Aviation Security Service Fee",
"semanticsCode": "OTHER",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "2.24"
},
{
"sequenceNumber": 2,
"description": "United States - Passenger Facility Charge",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_FEE",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "3.60"
},
{
"sequenceNumber": 3,
"description": "United States - Flight Segment Tax",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_TAX",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.00"
}
]
},
{
"originationAirportIATACode": "GFK",
"originationDateTime": "2015-12-30T17:19:00-0500",
"destinationAirportIATACode": "MSP",
"destinationDateTime": "2015-12-30T18:34:00-0500",
"flightNumber": "OO 4656",
"couponNumber": "D187322",
"operatingAirlineCode": "DL",
"marketingCarrier": "DL1768Z",
"operatingCarrier": "OO4656B",
"classOfServiceCode": "T",
"fareBasisCode": "YAD1234",
"ticketDesignatorCode": "FSG*SFR",
"fare": "140.14",
"taxes": [
{
"authority": {
"addressCountry": "US"
},
"name": "Transportation Tax",
"rate": 7.50,
"amount": "10.51"
}
],
"lineItems": [
{
"sequenceNumber": 1,
"description": "United States - September 11th Security Fee",
"additionalDescription": "Passenger Civil Aviation Security Service Fee",
"semanticsCode": "OTHER",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "2.58"
},
{
"sequenceNumber": 2,
"description": "United States - Passenger Facility Charge",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_FEE",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.14"
},
{
"sequenceNumber": 3,
"description": "United States - Flight Segment Tax",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_TAX",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.00"
}
]
},
{
"originationAirportIATACode": "MSP",
"originationDateTime": "2015-12-30T19:25:00-0500",
"destinationAirportIATACode": "SEA",
"destinationDateTime": "2015-12-30T21:15:00-0700",
"flightNumber": "DL 2536",
"couponNumber": "D187322",
"operatingAirlineCode": "DL",
"marketingCarrier": "DL2536Z",
"operatingCarrier": "DL2536B",
"classOfServiceCode": "T",
"fareBasisCode": "YAD1234",
"ticketDesignatorCode": "FSG*SFR",
"fare": "194.98",
"taxes": [
{
"authority": {
"addressCountry": "US"
},
"name": "Transportation Tax",
"rate": 7.50,
"amount": "14.62"
}
],
"lineItems": [
{
"sequenceNumber": 1,
"description": "United States - September 11th Security Fee",
"additionalDescription": "Passenger Civil Aviation Security Service Fee",
"semanticsCode": "OTHER",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "3.58"
},
{
"sequenceNumber": 2,
"description": "United States - Passenger Facility Charge",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_FEE",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "5.76"
},
{
"sequenceNumber": 3,
"description": "United States - Flight Segment Tax",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_TAX",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "4.00"
}
]
}
]
}
],
"lineItems": [
{
"sequenceNumber": 1,
"description": "United States - September 11th Security Fee",
"additionalDescription": "Passenger Civil Aviation Security Service Fee",
"semanticsCode": "OTHER",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "22.40"
},
{
"sequenceNumber": 2,
"description": "United States - Passenger Facility Charge",
"additionalDescription": "",
"semanticsCode": "SEGFEE_AS_FEE",
"dateTime": "2015-11-29T19:15:55-0700",
"total": "36.00"
}
]
}
Generated Receipt Image

Car Rental
Receipt Data
{
"taxInvoice": true,
"reference": "ABCD1234",
"dateTime": "2016-09-29T15:05:00-0800",
"total": "112.71",
"taxesTotal": "8.27",
"subtotal": "104.44",
"currencyCode": "USD",
"seller": {
"name": "ACME Corporation",
"description": "",
"taxId": "123-21213",
"location": {
"name": "SNA Airport",
"number": "SNA34393",
"latitude": 47.616667,
"longitude": -122.333333,
"internetAddress": "https://www.acmecorporation.com",
"emailAddress": "sna_airport@acmecorporation.com",
"telephoneNumber": "123-456-7890",
"faxNumber": "",
"address": {
"streetAddress": "1 Airport Way",
"addressLocality": "Seattle",
"addressRegion": "WA",
"addressCountry": "US",
"postalCode": "90001"
}
}
},
"taxes": [
{
"authority": {
"addressCountry": "US",
"addressRegion": "WA"
},
"name": "Local Sales Tax",
"rate": 8.80,
"amount": "8.27"
}
],
"payments": [
{
"amount": "112.71",
"cardDetail": {
"cardType": "American Express",
"creditCardId": "1009",
"authorizationCode": "AB987654321"
}
}
],
"startDateTime": "2014-11-05T15:05:00-0800",
"endDateTime": "2014-11-07T15:05:00-0800",
"rentalDays": 2,
"discounts": [{
"discountCode": "NO-IRS",
"discountName": "The Family of the King shall pay less",
"discountRate": "Per Mile"
}
],
"rentalAgreementNumber": "570344843",
"confirmationNumber": "",
"vehicle": {
"registrationNumber": "",
"description": "KIA SORENTO 2WD",
"classReservedCode": "IDAR",
"classRentedCode": "IDAR",
"classChargedCode": "IDAR",
"engineSize": "2000",
"fuelType": "Petrol"
},
"distance": {
"totalDistance": 345.6,
"unit": "mi"
},
"odometerReadingOut": 31548,
"odometerReadingIn": 31893,
"additionalDriver": false,
"pickupLocation": {
"name": "House of Stark",
"address": {
"streetAddress": "1 Wolf Road",
"addressLocality": "Winterfell",
"addressCountry": "GB"
}
},
"dropoffLocation": {
"name": "The Iron Throne",
"address": {
"streetAddress": "42 Shadowblack Lane",
"addressLocality": "King's Landing",
"addressCountry": "GB"
}
},
"lineItems": [
{
"sequenceNumber": 1,
"reference": "",
"description": "2 DY@ 47.00",
"additionalDescription": "",
"semanticsCode": "DAYS",
"quantity": 1,
"total": "94.00",
"taxes": [
{
"authority": {
"addressCountry": "US",
"addressRegion": "CA"
},
"name": "Local Sales Tax",
"rate": 8.80,
"amount": "8.27"
}
]
},
{
"sequenceNumber": 2,
"reference": "",
"description": "11.11% FEE",
"additionalDescription": "",
"semanticsCode": "AIRPORTFEE",
"quantity": 1,
"total": "10.44"
}
]
}
Generated Receipt Image

Sample Receipts - Hotel
Receipt Data
{
"taxInvoice": true,
"reference": "6343430",
"dateTime": "2016-09-29T15:05:00-0800",
"total": "749.95",
"subtotal": "652.67",
"taxesTotal": "97.28",
"currencyCode": "CAD",
"seller": {
"name": "ACME Corporation",
"description": "",
"taxId": "123-21213",
"location": {
"name": "ACME Hotels",
"number": "ACME34393",
"latitude": 47.616667,
"longitude": -122.333333,
"internetAddress": "https://www.acmecorporation.com",
"emailAddress": "sna_hotel@acmecorporation.com",
"telephoneNumber": "123-456-7890",
"faxNumber": "",
"address": {
"streetAddress": "1 Hotel Way",
"addressLocality": "Seattle",
"addressRegion": "WA",
"addressCountry": "US",
"postalCode": "90001"
}
}
},
"taxes": [
{
"authority": {
"addressCountry": "CA"
},
"name": "Hotel Room Tax",
"rate": 11.00,
"amount": "66.88"
},
{
"authority": {
"addressCountry": "CA"
},
"name": "GST",
"rateType": "Standard",
"rate": 5.00,
"amount": "30.4"
}
],
"payments": [
{
"amount": "749.95",
"cardDetail": {
"cardType": "American Express",
"creditCardId": "1002",
"authorizationCode": "548283"
}
}
],
"property": {
"name": "Grand Hotel",
"number": "",
"latitude": 49.280011,
"longitude": -123.117024,
"internetAddress": "",
"emailAddress": "",
"telephoneNumber": "123-456-1999",
"faxNumber": "123-456-2502",
"address": {
"streetAddress": "433 Hotel Street",
"addressLocality": "Vancouver",
"addressRegion": "BC",
"addressCountry": "CA",
"postalCode": "v6b 6l9"
}
},
"checkInDateTime": "2016-08-25T21:11:00-0700",
"checkOutDateTime": "2016-08-27T11:09:00-0700",
"guests": [
{
"guestNameRecord": "ACME-Axxxxxxx1899",
"firstName": "Jon",
"lastName": "Snow",
"address": {
"streetAddress": "111 Black Castle",
"addressLocality": "Toronto",
"addressRegion": "ON",
"addressCountry": "CA",
"postalCode": "M2P 2B8"
}
}
],
"numberInParty": 1,
"room": {
"roomNumber": "1601",
"averageDailyRoomRate": "304.00"
},
"nightsStayed": 2,
"lineItems": [
{
"sequenceNumber": 1,
"dateTime": "2016-04-25T18:00:00-0700",
"reference": "RT1601",
"description": "Room Chrg Retail",
"semanticsCode": "ROOMRATE",
"quantity": 1,
"total": "304.00",
"taxes": [
{
"authority": {
"addressCountry": "CA"
},
"name": "Hotel Room Tax",
"rate": 11.00,
"amount": "33.44"
},
{
"authority": {
"addressCountry": "CA"
},
"name": "GST",
"rateType": "Standard",
"rate": 5.00,
"amount": "15.20"
}
]
},
{
"sequenceNumber": 2,
"dateTime": "2016-04-25T18:00:00-0700",
"reference": "RT1601",
"description": "Destination Marketing Fee",
"semanticsCode": "FEE",
"quantity": 1,
"total": "4.56"
},
{
"sequenceNumber": 3,
"dateTime": "2016-04-26T18:00:00-0700",
"reference": "4071",
"description": "Hidden Bar and Lounge",
"semanticsCode": "MINIBAR",
"quantity": 1,
"total": "31.55"
},
{
"sequenceNumber": 4,
"dateTime": "2016-04-26T18:00:00-0700",
"reference": "RT1601",
"description": "Room Chrg Retail",
"semanticsCode": "ROOMRATE",
"quantity": 1,
"total": "304.00",
"taxes": [
{
"authority": {
"addressCountry": "CA"
},
"name": "Hotel Room Tax",
"rate": 11.00,
"amount": "33.44"
},
{
"authority": {
"addressCountry": "CA"
},
"name": "GST",
"rateType": "Standard",
"rate": 5.00,
"amount": "15.20"
}
]
},
{
"sequenceNumber": 5,
"dateTime": "2016-04-26T18:00:00-0700",
"reference": "RT1601",
"description": "Destination Marketing Fee",
"semanticsCode": "FEE",
"quantity": 1,
"total": "4.56"
}
]
}
Generated Receipt Image

Ground Transport
Receipt Data
{
"taxInvoice": true,
"reference": "ADBXTF25",
"dateTime": "2016-09-29T15:39:46-0700",
"total": "65.00",
"taxesTotal": "5.69",
"subtotal": "59.87",
"currencyCode": "USD",
"broker": {
"name": "ACME Corporation",
"taxId": "123-21213",
"location": {
"name": "Seattle Downtown",
"number": "C3404",
"latitude": 47.6097,
"longitude": -122.3331,
"internetAddress": "http://www.acmecorporation.com/",
"emailAddress": "groundtransport@acmecorporation.com",
"telephoneNumber": "206-000-0000",
"faxNumber": "",
"address": {
"streetAddress": "1 Ground Transport Way",
"addressLocality": "Seattle",
"addressRegion": "WA",
"addressCountry": "US",
"postalCode": "90001"
}
}
},
"seller": {
"name": "John Smith",
"location": {
"address": {
"streetAddress": "225 42nd Ave S",
"addressLocality": "Seattle",
"addressRegion": "WA",
"addressCountry": "US",
"postalCode": "98103"
}
}
},
"taxes": [
{
"authority": {
"addressCountry": "US",
"addressRegion": "WA"
},
"name": "Local Sales Tax",
"rate": 9.50,
"amount": "5.69"
}
],
"payments": [
{
"amount": "65.00",
"cardDetail": {
"cardType": "Visa",
"creditCardId": "4321",
"authorizationCode": "AB123654789"
}
}
],
"classOfService": "BLACK",
"startDateTime": "2014-11-10T15:08:24-0500",
"endDateTime": "2014-11-10T15:39:46-0500",
"travelDuration": "PT21M22S",
"pickupLocation": {
"name": "Key Center Building, Bellevue, WA",
"latitude": 47.4436655,
"longitude": -122.2982266,
"address": {
"addressCountry": "US"
}
},
"dropoffLocation": {
"name": "Seattle-Tacoma International Airport, SeaTac, WA",
"latitude": 47.4489,
"longitude": -122.3094,
"address": {
"addressCountry": "US"
}
},
"distance": {
"totalDistance": 15.6,
"unit": "mi"
},
"driverNumber": "DFE154-8567",
"lineItems": [
{
"sequenceNumber": 1,
"reference": "",
"description": "Base Fare",
"additionalDescription": "",
"semanticsCode": "FEE",
"quantity": 1,
"total": "6.39",
"taxes": [
{
"authority": {
"addressCountry": "US",
"addressRegion": "WA"
},
"name": "Local Sales Tax",
"rate": 9.50,
"amount": "0.61"
}
]
},
{
"sequenceNumber": 2,
"reference": "",
"description": "Distance",
"additionalDescription": "",
"semanticsCode": "FEE",
"quantity": 1,
"total": "49.32",
"taxes": [
{
"authority": {
"addressCountry": "US",
"addressRegion": "WA"
},
"name": "Local Sales Tax",
"rate": 9.50,
"amount": "4.68"
}
]
},
{
"sequenceNumber": 3,
"reference": "",
"description": "Time",
"additionalDescription": "",
"semanticsCode": "FEE",
"quantity": 1,
"total": "4.16",
"taxes": [
{
"authority": {
"addressCountry": "US",
"addressRegion": "WA"
},
"name": "Local Sales Tax",
"rate": 9.50,
"amount": "0.40"
}
]
},
{
"sequenceNumber": 4,
"reference": "",
"description": "Rounding Down",
"additionalDescription": "",
"semanticsCode": "DISCOUNT",
"quantity": 1,
"total": "-0.56"
}
]
}
Generated Receipt Image

Rail (Multiple Tickets)
Receipt Data
{
"taxInvoice": true,
"reference": "VDFG4567",
"dateTime": "2099-11-10T16:04:49-0700",
"total": "394.00",
"subtotal": "394.00",
"taxesTotal": "0.00",
"currencyCode": "GBP",
"itineraryLocator": "DSFJKLT4967",
"seller": {
"name": "ACME Corporation",
"description": "",
"taxId": "321-654321",
"location": {
"name": "Headquarters",
"number": "",
"latitude": 41.8819,
"longitude": -87.6278,
"internetAddress": "http://www.voyages-sncf.com",
"emailAddress": "info@uk.voyages-sncf.com",
"telephoneNumber": "0330 822 0333",
"address": {
"streetAddress": "34 Tower View",
"addressLocality": "Kings Hill, WEST MALLING",
"addressCountry": "GB",
"postalCode": "ME19 4ED"
}
}
},
"payments": [
{
"amount": "394.00",
"cardDetail": {
"cardType": "American Express",
"creditCardId": "4002"
}
}
],
"railTickets": [
{
"ticketNumber": "C123456",
"recordLocator": "AZT222XFT9",
"issueDateTime": "2015-04-30T12:37:55-0700",
"passengerName": "John Doe",
"fare": "197.00",
"segments": [
{
"departureStation": "Paris Est",
"departureDateTime": "2015-11-25T10:00:00-0700",
"arrivalStation": "Frankfurt Main HBF",
"arrivalDateTime": "2015-11-26T12:00:00+0900",
"trainNumber": "9557",
"trainType": "TGV",
"classOfServiceCode": "First Class",
"fare": "98.50"
},
{
"departureStation": "Frankfurt Main HBF",
"departureDateTime": "2015-11-27T10:00:00-0700",
"arrivalStation": "Paris Est",
"arrivalDateTime": "2015-11-28T12:00:00+0900",
"trainNumber": "9558",
"trainType": "TGV",
"classOfServiceCode": "First Class",
"fare": "98.50"
}
]
},
{
"ticketNumber": "C123457",
"recordLocator": "AZT222XFT9",
"issueDateTime": "2015-04-30T12:37:55-0700",
"passengerName": "Jane Doe",
"fare": "197.00",
"segments": [
{
"departureStation": "Paris Est",
"departureDateTime": "2015-11-25T10:00:00-0700",
"arrivalStation": "Frankfurt Main HBF",
"arrivalDateTime": "2015-11-26T12:00:00+0900",
"trainNumber": "9557",
"trainType": "TGV",
"classOfServiceCode": "First Class",
"fare": "98.50"
},
{
"departureStation": "Frankfurt Main HBF",
"departureDateTime": "2015-11-27T10:00:00-0700",
"arrivalStation": "Paris Est",
"arrivalDateTime": "2015-11-28T12:00:00+0900",
"trainNumber": "9558",
"trainType": "TGV",
"classOfServiceCode": "First Class",
"fare": "98.50"
}
]
}
],
"lineItems": [
{
"sequenceNumber": 1,
"semanticsCode": "FEE",
"description": "Credit Card Fee",
"dateTime": "2015-11-10T16:04:49-0700",
"subtotal": "4.92",
"total": "4.92"
}
]
}
Generated Receipt Image

Response Codes-Receipts
Success Codes
| Code | Message | Information |
|---|---|---|
| 200 | OK | Your GET request succeeded. |
| 201 | Created | Your POST request succeeded. Please note that even though your request passed validation, the service still needs to create your receipt. Because of this processing time, your receipt might not be available for retrieval immediately. |
| 202 | Accepted | Your request was accepted. Please note that even though your request was accepted, the service still needs to process your receipt. Because of this processing time, your receipt might not be available for retrieval immediately. |
Failure Codes
| Code | Message | Response Body | Information |
|---|---|---|---|
| 400 | Bad Request | validationErrors JSON object |
An error occurred while validating your post against the JSON schema. The validationErrors object will contain detailed information about what caused the validation to fail. |
| Request body could not be parsed | This means that the body of your request was empty, or there was an error parsing it. | ||
| Link header must be provided and include a URL to a known receipt schema | The link header cannot be null or empty, and must include one of the supported receipt type JSON schemas followed by ;rel=describedBy. A list of supported schemas can be retrieved from the /schemas endpoint of this service. |
||
| The specified receipt schema is not valid | The schema specified in the link header was valid, but an error occurred when the service attempted to fetch the schema internally. | ||
| 401 | Unauthorized | User ID in the URL must match the ID in the sub claim of the JWT | This response occurs when the JWT used for authentication is valid, but doesn't match the correct user. When using a user JWT, the request must be to a URL for the same user that is represented in the JWT. For more information on the process of obtaining a JWT, see the Authentication service documentation. |
| 403 | Forbidden | None | Authentication failed for some reason. A 403 will be returned if there is no JWT in the Authorization header of the request, or if the JWT is invalid or expired. This response is also for cases where the JWT does not include the scope required to fulfill the request. For more information on JWTs and scopes, see the Authentication service documentation. |
| 404 | Not Found | None | The receipt(s) you requested could not be found. Check that the receipt and/or user ID that you used are correct. |
| 413 | Max file size exceeded | None | The image you posted exceeded the limit of 5MB. |
| 415 | Unsupported Media Type | Specified Content-Type is not supported | The receipt service currently supports receipt data formatted as JSON. The Content-Type header must have the value application/json or the request will fail. |
| Invalid image type | Images must be .png, .jpg, .jpeg, .tiff, or .gif. |
||
| 500 | Internal Server Error | Internal error | This response is for generic internal server errors. Something went wrong, and we're probably already trying to fix it! |
| Unable to save receipt into the database | An error occurred while trying to update the state of the receipt. | ||
| Could not get available receipts | An error occurred while trying to fetch receipts for a user by state. |
Receipt Image
Image v1
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
The SAP Concur Imaging Web service allows clients to manage the receipt images attached to expense reports and the images attached to invoices. Clients can retrieve existing images by reportID, image ID, or invoiceID, and upload new images to a user, expense entry, report, or invoice.
The Imaging web service supports the following image formats:
application/pdfwhich has not been encrypted or password protected.image/jpgimage/jpegimage/png
The maximum file size allowed is 10 MB.
Scope Usage
| Name | Description | Endpoint |
|---|---|---|
IMAGE |
Add or Retrieve Report and Line Item Images. | GET, POST |
Product Restrictions
SAP Concur products are highly configurable, and not all clients will have access to all features.
Partner developers must determine which configurations are required for their solution prior to the review process.
Existing clients can work with SAP Concur Advantage Technical Services to create custom applications that work with their configuration.
Post an image
Request
URI
Templates
https://www.concursolutions.com/api/image/v1.0/receipt
https://www.concursolutions.com/api/image/v1.0/expenseentry/{entryId}
https://www.concursolutions.com/api/image/v1.0/invoice/{requestId}
https://www.concursolutions.com/api/image/v1.0/report/{reportId}
Parameters
Required: One of these parameters is always required.
| Name | Type | Format | Description |
|---|---|---|---|
receipt |
string |
- | Uploads a receipt image and associates it with the OAuth consumer. The user can view the image in the receipt management section of SAP Concur. |
entryReceiptID/{entryReceiptId} |
string |
- | Obtains a short-lived URL (15 minute ttl) that can be rendered to obtain the receipt image. |
expenseentry/{entryID} |
string |
- | Uploads a receipt image and associates it with the expense entry that matches the supplied entry ID. Once an image is attached to the entry, you cannot append additional images. |
invoice/{requestID} |
string |
- | Uploads an invoice image and associates it with the invoice that matches the supplied request ID. Each invoice is uniquely identified by the request ID value. Once an image is attached to the invoice, you cannot append additional images. The Concur Invoice product is required to use this endpoint. Currently you must use the Invoice user interface to get the Request ID value. |
report/{reportID} |
string |
- | Uploads a receipt image and associates it with the report that matches the supplied report ID. If a report image already exists for the report, the new image will be appended to the existing image. |
Headers
- RFC 7235 Authorization (Required) - Authorization header with OAuth token for valid SAP Concur user. The SAP Concur user that authenticates during the OAuth process for this request must either be the user associated with this image, or have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. These administrative roles allow the user to manage data for the entire company.
- RFC 7231 Content-Type
application/pdf,image/jpg,image/jpeg,image/png
- RFC 7230 Content-Length
Payload
A byte array containing the image data.
Response
Status Codes
Headers
- RFC 7231 Content-Type:
application/xml
Payload
Example
Request
This example contains a truncated (see the ellipsis) 64-bit encoded string representation of the image for illustration purposes only. This example demonstrates one of the endpoints available.
POST https://www.concursolutions.com/api/image/v1.0/receipt
Authorization: OAuth {token}
Content-Length: 65536
Content-Type: image/jpeg
/9j/4AAQSkZJRgABAQEAyADIAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0a
HBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIy
MjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAkiBqQDASIA
AhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQA
AAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3
ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWm
p6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QAHwEA
AwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEE ...
Response
HTTP/1.1 201 Created
Content-Type: application/xml
<Image xmlns="http://www.concursolutions.com/api/image/2011/02" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Id>aBcDeMwbl34xnwdkUw5ZjDsggDl2$pyoy31$pnGaHAywmPrpbAmE</Id>
<Url />
</Image>
Get an image URL
Retrieves a URL to the following images:
- Receipt
- Expense entry
- Invoice
- Expense Report (PDF)
- If receipts have been uploaded to specific expense entries, they will all be bundled into one PDF at the report level.
The URL is valid for 30 minutes after the request.
Request
URI
Template
https://www.concursolutions.com/api/image/v1.0/receipt/{imageId}
https://www.concursolutions.com/api/image/v1.0/expenseentry/{entryId}
https://www.concursolutions.com/api/image/v1.0/invoice/{requestId}
https://www.concursolutions.com/api/image/v1.0/report/{imageId}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
receipt/{imageId} |
string |
- | The {keyword}/{identifier} for the desired receipt. |
expenseentry/{entryID} |
string |
- | The {keyword}/{identifier} for the desired expense entry. The entryId is returned in the RpeKey within ExpenseEntry portion of the response from the Expense Report Full Details v1.1 API. |
invoice/{requestID} |
string |
- | The {keyword}/{identifier} for the desired payment request. The Concur Invoice product is required to use this endpoint. Currently you must use the Invoice user interface to get the Request ID value. |
report/{imageId} |
string |
- | The {keyword}/{identifier} for the desired report. |
Headers
- RFC 7235 Authorization containing an OAuth token for a valid SAP Concur user. The OAuth consumer must be the owner of the report to which the image is attached.
- RFC 7231 Accept:
application/xml
Payload
None
Response
Status Codes
Headers
- RFC 7231 Content-Type:
application/xml
Payload
Example
Request
This example demonstrates one of the endpoints available.
GET /api/image/v1.0/expenseentry/A2C40CEE415B43B2A0BE
Authorization: OAuth {token}
Accept: application/xml
Response
200 OK
Content-Type: application/xml
<Image xmlns="http://www.concursolutions.com/api/image/2011/02" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Id>A2C40CEE415B43B2A0BE</Id>
<Url>https://api.example.com/getImage?cid=able999999&val=F9B35244G86</Url>
</Image>
Schema
Image
The Image schema provides metadata about an image within the system.
| Name | Type | Format | Description |
|---|---|---|---|
Id |
string |
- | The unique identifier of the image. |
Url |
string |
- | The URL for the image. Note that special characters will be XML-encoded. You will need to unencode any special characters before using the link. This element is empty when uploading images. |
C# Code Example
The following example in C# illustrates how to read the source image file as an array of bytes and pass that data into the request.
HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
request.Method = "POST";
request.ContentType = "application/pdf";
request.Headers.Add("Authorization", signature);
using (FileStream fs = new FileStream(pathToImageFile, FileMode.Open, FileAccess.Read))
{
using (BinaryReader br = new BinaryReader(fs))
{
byte[] image = br.ReadBytes((int)fs.Length);
request.ContentLength = image.Length;
Stream ds = request.GetRequestStream();
ds.Write(image, 0, image.Length);
ds.Close();
}
}
HttpWebResponse webresponse = request.GetResponse();
Receipt Image v3
- Scope Usage
- Retrieve a list of all receipt images
- Retrieve a receipt image by ID
- Create a new receipt image
- Append a receipt image
- Delete a receipt image
- Schema
The SAP Concur Receipt Image API allows for the management of receipt images attached to expense reports, expense entries, and payment requests. You can retrieve existing images by Image ID, and upload new images to a User. This API allows you to upload images in a predefined format and size targeting a specific resource or user in SAP Concur. You can also pull images down from SAP Concur by either displaying them in the browser or downloading the image content to save locally.
Note: This API is not designed to obtain the receipt images attached to an expense report. If you are an Enterprise Partner creating integrations that are intended to obtain final-approved Expense or Invoice data, and the accompanying receipt images that substantiate those transactions you will need to use Image v1. These scenarios include, but are not limited to: ERP integrations for financial journal entry postings, VAT reclaim integrations that obtain transactions to calculate VAT reclaim, project billing integrations used to substantiate expenses billed back, etc.
Receipt Image v3 - Scope Usage
| Name | Description | Endpoint |
|---|---|---|
IMAGE |
Add or Retrieve Report and Line Item Images. | GET, POST, PUT, DELETE |
Retrieve a List of All Receipt Images
GET /api/v3.0/expense/receiptimages
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
offset |
string |
query |
Starting page offset |
limit |
Int32 |
query |
Number of records to return (default 25) |
user |
string |
query |
The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter. |
Retrieve a Receipt Image by ID
GET /api/v3.0/expense/receiptimages/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required ReceiptImage ID |
user |
string |
query |
The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter. |
Example
The above GET request produces this response:
<Image xmlns="http://www.concursolutions.com/api/image/2011/02" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Id>sample</Id>
<Url>https://imagingupload.concursolutions.com/file/p00884704c6o/5A789811F139BC89D9C42DDE5FEE2A655BB7C2A375E9C481FA0BE92FFF690E298F119925A5C834385C8D62AE5FC4E65AC0F53E4C7273C14A4E71D4264F104882H142570AF84FBEEEC439486FE89E44D2F?id=51253775812C4750888F2e=p00884704c6o3t=AN</Url>
</Image>
Copy and paste the URL into a browser session to render the image. This is a temporary URL.
Create a New Receipt Image
POST /api/v3.0/expense/receiptimages
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
user |
string |
query |
The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter. |
image |
file |
body |
Required Image data file |
Append a Receipt Image
PUT /api/v3.0/expense/receiptimages/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required ID of the receipt image to update |
user |
string |
query |
The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter. |
image |
file |
body |
Required Image data file |
Delete a Receipt Image
DELETE /api/v3.0/expense/receiptimages/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required ID of the receipt image to delete |
user |
string |
query |
The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter. |
Receipt Image v3 - Schema
Receipt Images
| Name | Type | Format | Description |
|---|---|---|---|
Items |
Array | Receipt Image | The result collection. |
NextPage |
string | - | The URI of the next page of results, if any. |
Receipt Image
| Name | Type | Format | Description |
|---|---|---|---|
ID |
string | - | The unique identifier of the resource. |
URI |
string | - | The URI to the resource. |
Request v4
Getting Started - Request v4
Menu
- Getting Started
- Request
- Workflow
- Expected Expense
- Request Cash Advance
- Request Policy
- Travel Agency
- Schema
- HTTP Status Codes
- Run in Postman
Concur Request automates the spend request and approval process for both travel and everyday expenses, giving you the data you need to accurately track and better control spending. By increasing visibility into planned expenses and up-to-date budget data, you can make strategic spending decisions before any spending actually occurs. The Request API provides many possibilities, particularly Requests creation and transition into the approval workflow.
Version 4.0 of Request API works only with the new Authentication API.
Getting Started
- Overview
- Prior Versions
- Process Flow
- Products and Editions
- Scope Usage
- Dependencies
- Access Token Usage
Getting Started - Overview
The Request v4 API exposes five different resources:
| Resource | Description |
|---|---|
| Request | You can read, create, update or delete a Request and get the list of existing Requests. |
| Workflow | You can perform action in the approval workflow of a Request (submit, approve, cancel...) |
| Expected Expense | You can read, create, update or delete an expected expense, and get the list of expected Expenses for a specific Request. |
| Request Policy | You can get the list of existing Request policies. |
| Travel Agency | You can get the description of a Travel Agency office. |
These resources are used to manage documents used for pre-spend authorizations within Concur Request.
Getting Started - Prior Versions
Getting Started - Process Flow

Getting Started - Products and Editions
- Concur Request Professional Edition
- Concur Request Standard Edition
Getting Started - Scope Usage
| Name | Description | Endpoint |
|---|---|---|
travelrequest.write |
Read and write Requests | GET, POST, PUT, DELETE |
Getting Started - Dependencies
SAP Concur clients must purchase Concur Request in order to use this API. This API may require for some use cases to consume the following additional SAP Concur APIs:
- User profile, to retrieve the
userId- required in most of the endpoints when accessed via a Company Token. - [List], to retrieve the
listItemId- required in the management of custom fields related to list items. Currently in externalisation process, please liaise with List API owner team for further update.
Getting Started - Access Token Usage
This API supports both company level and user level access tokens.
Company Access Token
- The
userIdparameter is required to provide the user identity of who made the API call. - Does not have an associated role.
User Access Token
- The
userIdparameter is not required. - Requires the Web Service Admin role to call the API.
Request v4 - Request Resources
Menu
- Getting Started
- Request
- Workflow
- Expected Expense
- Request Cash Advance
- Request Policy
- Travel Agency
- Schema
- HTTP Status Codes
- Run in Postman
Request Resources
- Create a new Request
- Get the list of existing Requests
- Get the content of an existing Request
- Update the content of an existing Request
- Delete an existing Request
- Get the list of comments for an existing Request
- Get the list of cash advances assigned to an existing Request
- Get the list of exceptions linked to an existing Request
Create a new Request
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
POST {datacenter}/travelrequest/v4/requests
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
userId |
string |
- | The unique identifier of the Request owner for whom the Request will be created. The corresponding user name will be displayed in the audit trail of the Request. Required when connecting with a Company token, if empty a 400 missingRequiredParam error code will be displayed. |
Payload
Since this endpoint is performing a Request creation, specifying an id field in the payload is not allowed.
A newly allocated id value will be returned upon successful Request creation.
HTTP Response
Request Resources - HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Request - The created Request.
Example
HTTP Request
POST https://us.api.concursolutions.com/travelrequest/v4/requests
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
"businessPurpose": "Trip to Lyon for company training",
"comment": "Company training requires to go to Lyon",
"custom1": {
"value": "Training part of IT Service"
},
"custom2": {
"value": "8422A66A9B0142458020D9BCD4351D38"
},
"custom3": {
"value": "5A0F9AF6B92E34468698040C915688BF"
},
"custom4": {
"value": "3F54AE68BA66EF49A5984E5197202A4D"
},
"endDate": "2018-07-03",
"endTime": "22:00",
"startDate": "2018-07-01",
"startTime": "07:15",
"name": "Company Training - JULY 2018",
"mainDestination": {
"city": "Lyon, FRANCE",
"countryCode": "FR",
"countrySubDivisionCode": "FR-69",
"name": "Lyon, FRANCE"
},
"policy": {
"id": "F4C8BD31CA9D4D6292795BE687EB9B2A"
},
"travelAgency": {
"id": "2EC038D7C3CBBE4ABA0914425064D34F"
}
}
HTTP Response
201 Created
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/CED5E9CD8FC1424488F9331ACF956E73",
"id": "CED5E9CD8FC1424488F9331ACF956E73",
"approvalStatus": {
"code": "NOT_SUBMITTED",
"name": "Not Submitted"
},
"approved": false,
"businessPurpose": "Trip to Lyon for company training",
"canceledPostApproval": false,
"closed": false,
"comment": "Company training requires to go to Lyon",
"creationDate": "2018-05-25T08:08:59.000Z",
"custom1": {
"value": "Training part of IT Service"
},
"custom2": {
"code": "CEN3",
"value": "8422A66A9B0142458020D9BCD4351D38"
},
"custom3": {
"code": "CEN3PRO1",
"value": "5A0F9AF6B92E34468698040C915688BF"
},
"custom4": {
"code": "TRAINING",
"value": "3F54AE68BA66EF49A5984E5197202A4D"
},
"endDate": "2018-07-03",
"endTime": "22:00",
"everSentBack": false,
"expenses": [],
"highestExceptionLevel": "WARNING",
"lastModified": "2018-05-25T08:08:59.000Z",
"mainDestination": {
"countryCode": "FR",
"countrySubDivisionCode": "FR-69",
"city": "Lyon, FRANCE",
"name": "Lyon, FRANCE"
},
"name": "Company Training - JULY 2018",
"owner": {
"firstName": "John",
"id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
"lastName": "Doe"
},
"pendingApproval": false,
"policy": {
"id": "F4C8BD31CA9D4D6292795BE687EB9B2A"
},
"requestId": "333U",
"startDate": "2018-07-01",
"startTime": "07:15",
"totalApprovedAmount": {
"value": 0,
"currency": "USD"
},
"totalPostedAmount": {
"value": 0,
"currency": "USD"
},
"totalRemainingAmount": {
"value": 0,
"currency": "USD"
},
"travelAgency": {
"href": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/2EC038D7C3CBBE4ABA0914425064D34F",
"id": "2EC038D7C3CBBE4ABA0914425064D34F",
"template": "https://https://us.api.concursolutions.com/travelrequest/v4/travelagencies/{id}"
},
"type": {
"code": "TRAVEL",
"label": "Travel"
},
"operations": [
{
"rel": "submit",
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/CED5E9CD8FC1424488F9331ACF956E73/submit"
}
]
}
Request Resources - Get the list of existing Requests
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/requests
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
view |
string |
- | Name of the view defining the scope of the Requests to get. Supported values:ALL: Get all existing Requests for a user (relevant only for the traveler).ACTIVEGet all active Requests. Does not include cancelled Requests. Approved Requests included are aged less than three months based on current date and must not be in closed status.UNSUBMITTED: Get all the unsubmitted Requests (relevant only for the traveler).PENDING: Get all the Requests that are submitted but not yet approved (relevant only for the traveler).VALIDATED: Get all the approved Requests for a user (relevant only for the traveler). Closed Requests are included in this view.APPROVED: Get all the approved Requests by a user (relevant only for the approver). Closed Requests are included in this view.CANCELED: Get all the cancelled Requests for a user (relevant only for the traveler). Cancelled could include closed/not closed Requests.CLOSED: Get all the closed Requests for a user (relevant only for the traveler). Includes canceled then closed Request as well as approved then closed Requests.SUBMITTED: Get all the submitted Requests for a user (relevant only for the traveler). Submitted does not include cancelled requests.TOAPPROVE: Get all Requests to be approved by the user (relevant only for the approver).PENDINGEBOOKING: Approved Requests awaiting Concur Travel booking(s).PENDINGPROPOSAL: Get all Requests submitted to a Travel Agency (TMC) step (relevant only for the TMC agent), userId is required.PROPOSALAPPROVED: Get all the approved Requests by a user (relevant only for the TMC agent), userId is required.PROPOSALCANCELED: Get all the cancelled Requests for a user (relevant only for the TMC agent), userId is required.If no view value is sent, the default view ALL will be used. |
userId |
string |
- | Associated with a traveler view: the unique identifier of the Request owner to use when searching for Requests. Associated with an approver view: the unique identifier of the approver to user when searching for Requests. Associated with a TMC agent view, Required, the unique identifier of the TMC agent to use. This TMC agent user must have a default Travel Agency assigned in its profile corresponding to the Travel Agency assigned to the Requests |
start |
integer |
- | Pagination: index of the first record. Default: 0 |
limit |
integer |
- | Number of records to return per page. Default: 10. Maximum limit: 100, if higher value or digit value is set, a 400 error code will be displayed. |
approvedBefore |
dateTime |
yyyy-MM-dd'T'HH:mm:ss.SSS'Z' or yyyy-MM-dd |
Returns Requests that have been approved before the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time should be in UTC. when time is missing it is defaulted to midnight. |
approvedAfter |
dateTime |
yyyy-MM-dd'T'HH:mm:ss.SSS'Z' or yyyy-MM-dd |
Returns Requests that have been approved after the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time should be in UTC. When time is missing it is defaulted to midnight. |
modifiedBefore |
dateTime |
yyyy-MM-dd'T'HH:mm:ss.SSS'Z' or yyyy-MM-dd |
Returns Requests in which the associated dependents (Header, Expected expenses, Segments, Allocations, Attendees, Comments) were modified before the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time should be in UTC. When time is missing it is defaulted to midnight. |
modifiedAfter |
dateTime |
yyyy-MM-dd'T'HH:mm:ss.SSS'Z' or yyyy-MM-dd |
Returns Requests in which the associated dependents (Header, Expected expenses, Segments, Allocations, Attendees, Comments) were modified after the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time should be in UTC. When time is missing it is defaulted to midnight. |
sortField |
string |
- | The name of the field on which to sort. Supported values: startDate, approvalStatus, requestId. If no view value is sent, the default sortField startDate will be used. |
sortOrder |
string |
- | Sort order. Supported values: ASC, DESC. If no view value is sent, the default sortOrder DESC will be used. |
Payload
None.
HTTP Response
Request Resources - HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Example
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/requests?view=ALL&limit=10&start=0
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
{
"data": [{
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/2B19A2438CD6664A9C44E0F4D39E870A",
"id": "2B19A2438CD6664A9C44E0F4D39E870A",
"approvalStatus": {
"code": "SUBMITTED",
"name": "Submitted & Pending Approval"
},
"approved": false,
"approver": {
"id": "86ac9588-5032-3fa7-b3cc-20e97d2d7146",
"firstName": "Jason",
"lastName": "McCafee"
},
"businessPurpose": "PMP Training in Nantes",
"canceledPostApproval": false,
"closed": false,
"comment": "Plane too early in the morning, if possible book Hotel and arrive the day before\n",
"creationDate": "2018-09-03T11:53:02.000Z",
"endDate": "2018-10-08",
"everSentBack": true,
"expenses": [],
"name": "PMP Training - OCTOBER",
"owner": {
"firstName": "John",
"id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
"lastName": "Doe"
},
"pendingApproval": true,
"requestId": "3AT7",
"startDate": "2018-10-08",
"startTime": "05:00",
"submitDate": "2018-09-03T11:55:00.000Z",
"totalApprovedAmount": {
"value": 213.06,
"currency": "USD"
},
"totalPostedAmount": {
"value": 213.06,
"currency": "USD"
},
"totalRemainingAmount": {
"value": 213.06,
"currency": "USD"
},
"type": {
"code": "TRAVEL",
"label": "Travel"
}
},
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/4CCBAE73F3E14346AE93253480F5C409",
"id": "4CCBAE73F3E14346AE93253480F5C409",
"approvalStatus": {
"code": "NOT_SUBMITTED",
"name": "Not Submitted"
},
"approved": false,
"businessPurpose": "Client meeting for project KIWI",
"canceledPostApproval": false,
"closed": false,
"comment": "Need to arrive the day before as meeting is in Company office early in the morning\n",
"creationDate": "2018-09-03T11:44:10.000Z",
"endDate": "2018-09-20",
"everSentBack": false,
"expenses": [],
"name": "Client meeting in Berlin",
"owner": {
"firstName": "John",
"id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
"lastName": "Doe"
},
"pendingApproval": false,
"requestId": "3AT6",
"startDate": "2018-09-18",
"startTime": "17:30",
"submitDate": "2018-09-03T11:49:32.000Z",
"totalApprovedAmount": {
"value": 478.56,
"currency": "USD"
},
"totalPostedAmount": {
"value": 478.56,
"currency": "USD"
},
"totalRemainingAmount": {
"value": 478.56,
"currency": "USD"
},
"type": {
"code": "TRAVEL",
"label": "Travel"
}
}
],
"operations": [{
"rel": "next",
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests?view=ALL&limit=3&start=3"
},
{
"rel": "first",
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests?view=ALL&limit=3&start=0"
},
{
"rel": "last",
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests?view=ALL&limit=3&start=135"
}
]
}
Request Resources - Get the content of an existing Request
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/requests/{requestUuid}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
requestUuid |
string |
- | Required The unique identifier of the Request. |
userId |
string |
- | The unique identifier of the user getting the content of the Request. If empty when using a Company token the default system user will be assumed to perform the action. |
Payload
None.
HTTP Response
Request Resources - HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Request - The Request having {requestUuid} as unique identifier.
Example
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2",
"id": "224AF3CDCC2A5244A37C72FA5770C6F2",
"approvalStatus": {
"code": "NOT_SUBMITTED",
"name": "Not Submitted"
},
"approved": false,
"businessPurpose": "Client meeting for project KIWI",
"canceledPostApproval": false,
"cashAdvances": {
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/cashadvances",
"id": "224AF3CDCC2A5244A37C72FA5770C6F2",
"template": "https://us.api.concursolutions.com/travelrequest/v4/requests/{id}/cashadvances"
},
"closed": false,
"comment": "Need to arrive the day before for meeting in Company Office",
"comments": {
"href": "http://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/comments",
"id": "224AF3CDCC2A5244A37C72FA5770C6F2",
"template": "http://us.api.concursolutions.com/travelrequest/v4/requests/{id}/comments"
},
"creationDate": "2018-05-25T07:31:33.000Z",
"custom1": {
"value": "Kick-off meeting for project KIWI"
},
"custom2": {
"code": "CEN1",
"value": "54F0CBD8833CB348BD45A6C7C621C951"
},
"custom3": {
"code": "CEN1PRO2",
"value": "441D6FC50766A044ACC07FF780F1BAD9"
},
"custom4": {
"code": "CLIENTPROJECT",
"value": "050BE16A7BF72948810AFDBC9069BD8E"
},
"endDate": "2018-07-17",
"endTime": "19:30",
"everSentBack": false,
"exceptions": {
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/exceptions",
"id": "224AF3CDCC2A5244A37C72FA5770C6F2",
"template": "https://us.api.concursolutions.com/travelrequest/v4/requests/{id}/exceptions"
},
"expensePolicy": {
"id": "A6D42A825114472FAF402180E20B3751"
},
"expenses": [
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1",
"id": "B5FB8991E390474E875D6FD5BB1FDAF1",
"template": "https://us.api.concursolutions.com/travelrequest/v4/expenses/{id}"
},
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/D65BDBD5D980F6498D67A92B06A457B0",
"id": "D65BDBD5D980F6498D67A92B06A457B0",
"template": "hhttps://us.api.concursolutions.com/travelrequest/v4/expenses/{id}"
},
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/C286A46A2DDF984EA28E41CEA278667D",
"id": "C286A46A2DDF984EA28E41CEA278667D",
"template": "https://us.api.concursolutions.com/travelrequest/v4/expenses/{id}"
}
],
"lastModified": "2018-05-25T07:34:01.000Z",
"mainDestination": {
"countryCode": "DE",
"countrySubDivisionCode": "DE-BE",
"city": "Berlin, GERMANY",
"name": "Berlin, GERMANY"
},
"name": "Client meeting in Berlin - JULY",
"owner": {
"firstName": "John",
"id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
"lastName": "Doe"
},
"pendingApproval": false,
"policy": {
"id": "00497B95D8055849A1B217C8D05FFB86"
},
"requestId": "333T",
"startDate": "2018-07-15",
"startTime": "06:00",
"totalApprovedAmount": {
"value": 494.56,
"currency": "USD"
},
"totalPostedAmount": {
"value": 494.56,
"currency": "USD"
},
"totalRemainingAmount": {
"value": 494.56,
"currency": "USD"
},
"travelAgency": {
"href": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/2EC038D7C3CBBE4ABA0914425064D34F",
"id": "2EC038D7C3CBBE4ABA0914425064D34F",
"template": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/{id}"
},
"type": {
"code": "TRAVEL",
"label": "Travel"
},
"operations": [
{
"rel": "submit",
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/submit"
}
]
}
Request Resources - Update the content of an existing Request
Update of the following fields is supported : comment, startDate, startTime, endDate, endTime, expensePolicy, name, businessPurpose, mainDestination, travelAgency, and custom fields. Other fields will be ignored.
This endpoint supports partial update. You may submit only the fields to update in the body, fields not present in the body will remain unchanged. To clear a field use the value null (without quotes).
id field is not mandatory in the payload, if provided the value must match the requestUuid parameter.
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
PUT {datacenter}/travelrequest/v4/requests/{requestUuid}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
requestUuid |
string |
- | Required The unique identifier of the Request. |
userId |
string |
- | The unique identifier of the user performing the update. Required when connecting with a Company token. If empty a 400, missingRequiredParam error code will be displayed. |
Payload
HTTP Response
Request Resources - HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Request - The Request having {requestUuid} as unique identifier after update.
Example
HTTP Request
PUT https://us.api.concursolutions.com/travelrequest/v4/requests/E82B0B803671004B9A5D952F34FBD01E
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
"businessPurpose": "Trip to Lyon for company training - Modification of dates and Cost center + Custom Field",
"comment": "Company training requires to go to Lyon - Dates and service changed",
"custom1": {
"value": "Training part of IT Service"
},
"custom2": {
"value": "54F0CBD8833CB348BD45A6C7C621C951"
},
"custom3": {
"value": "441D6FC50766A044ACC07FF780F1BAD9"
},
"custom4": {
"value": "3F54AE68BA66EF49A5984E5197202A4D"
},
"endDate": "2018-07-09",
"endTime": "19:00",
"id": "053A479B3C9DD847B02A203C657AE26B",
"startDate": "2018-07-07",
"startTime": "06:15",
"name": "Company Training - JULY 2018",
"mainDestination": {
"city": "Lyon, FRANCE",
"countryCode": "FR",
"countrySubDivisionCode": "FR-69",
"name": "Lyon, FRANCE"
},
"policy": {
"id": "F4C8BD31CA9D4D6292795BE687EB9B2A"
},
"travelAgency": {
"id": "2EC038D7C3CBBE4ABA0914425064D34F"
}
}
HTTP Response
200 OK
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B",
"id": "053A479B3C9DD847B02A203C657AE26B",
"approvalStatus": {
"code": "NOT_SUBMITTED",
"name": "Not Submitted"
},
"approved": false,
"businessPurpose": "Trip to Lyon for company training - Modification of dates and Cost center + Custom Field",
"canceledPostApproval": false,
"closed": false,
"comment": "Company training requires to go to Lyon - Dates and service changed",
"creationDate": "2018-05-25T09:17:25.000Z",
"custom1": {
"value": "Training part of IT Service"
},
"custom2": {
"code": "CEN1",
"value": "54F0CBD8833CB348BD45A6C7C621C951"
},
"custom3": {
"code": "CEN1PRO2",
"value": "441D6FC50766A044ACC07FF780F1BAD9"
},
"custom4": {
"code": "TRAINING",
"value": "3F54AE68BA66EF49A5984E5197202A4D"
},
"endDate": "2018-07-09",
"endTime": "19:00",
"everSentBack": false,
"expenses": [],
"lastModified": "2018-05-25T09:24:34.000Z",
"mainDestination": {
"countryCode": "FR",
"countrySubDivisionCode": "FR-69",
"city": "Lyon, FRANCE",
"name": "Lyon, FRANCE"
},
"name": "Company Training - JULY 2018",
"owner": {
"firstName": "John",
"id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
"lastName": "Doe"
},
"pendingApproval": false,
"policy": {
"id": "F4C8BD31CA9D4D6292795BE687EB9B2A"
},
"requestId": "333X",
"startDate": "2018-07-07",
"startTime": "06:15",
"totalApprovedAmount": {
"value": 0,
"currency": "USD"
},
"totalPostedAmount": {
"value": 0,
"currency": "USD"
},
"totalRemainingAmount": {
"value": 0,
"currency": "USD"
},
"travelAgency": {
"href": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/2EC038D7C3CBBE4ABA0914425064D34F",
"id": "2EC038D7C3CBBE4ABA0914425064D34F",
"template": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/{id}"
},
"type": {
"code": "TRAVEL",
"label": "Travel"
},
"operations": [
{
"rel": "submit",
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B/submit"
}
]
}
Request Resources - Delete an existing Request
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
DELETE {datacenter}/travelrequest/v4/requests/{requestUuid}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
requestUuid |
string |
- | Required The unique identifier of the Request. |
userId |
string |
- | The unique identifier of the user performing the deletion. Required when connecting with a Company token. If empty a 400, missingRequiredParam error code will be displayed. |
Payload
None.
HTTP Response
Payload
None.
Example
HTTP Request
DELETE https://us.api.concursolutions.com/travelrequest/v4/requests/0D4DC4589D33AC4B9AF2E8B548C7AD2C
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
true
Request Resources - Get the list of comments for an existing Request
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/requests/{requestUuid}/comments
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
requestUuid |
string |
- | Required The unique identifier of the Request. |
Payload
None.
HTTP Response
Request Resources - HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Example
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/comments
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
[
{
"author": {
"firstName": "Steve",
"lastName": "Smith"
},
"creationDateTime": "2019-07-12T11:51:14.000Z",
"isLatest": true,
"value": "Please specify an amount less than 600 Euros"
},
{
"author": {
"firstName": "John",
"lastName": "Doe"
},
"creationDateTime": "2019-07-12T11:11:39.000Z",
"isLatest": false,
"value": "Please review the business meal excepted expense to confirm required amount"
}
]
Request Resources - Get the list of cash advances assigned to an existing Request
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/requests/{requestUuid}/cashadvances
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
requestUuid |
string |
- | Required The unique identifier of the Request. |
userId |
string |
- | The unique identifier of the user getting the list of the cash advances assigned to a Request. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed. |
Payload
None.
HTTP Response
Request Resources - HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
ResourceLink - The resource link leading to the created cash advance.
Example
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/cashadvances
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
[
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/cashadvances/EF3E237ACAA3C449B808BA75BDD049FA",
"id": "EF3E237ACAA3C449B808BA75BDD049FA",
"template": "https://us.api.concursolutions.com/travelrequest/v4/cashadvances/{id}"
},
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/cashadvances/9DDAB28B89828A4497209062F4AF87D6",
"id": "9DDAB28B89828A4497209062F4AF87D6",
"template": "https://us.api.concursolutions.com/travelrequest/v4/cashadvances/{id}"
}
]
Request Resources - Get the list of exceptions linked to an existing Request
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/requests/{requestUuid}/exceptions
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
requestUuid |
string |
- | Required The unique identifier of the Request. |
userId |
string |
- | The unique identifier of the user getting the content of the exceptions. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed. |
Payload
None.
HTTP Response
Request Resources - HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Example
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/exceptions
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
[
{
"code": "CALWARN2",
"level": 1,
"message": "The requested Cash Advance exceeds the limit allowed by your company policy which is defined as the total of Daily Allowances (€0.00). Please update the requested amount accordingly.",
"isBlocking": false,
"source": {
"id": "DAF37B097DB82D4D9A15E9F3F7E460C9",
"href": "https://emea.api.concursolutions.com/v4/requests/DAF37B097DB82D4D9A15E9F3F7E460C9?compact=false",
"type": "HEADER"
},
"parameters": {}
}
]
Request v4 - Workflow Resources
Menu
- Getting Started
- Request
- Workflow
- Expected Expense
- Request Cash Advance
- Request Policy
- Travel Agency
- Schema
- HTTP Status Codes
- Run in Postman
Workflow Resources
Manage workflow transitions for a Request.
Move an existing Request in the approval workflow
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
The HATEOAS links for actions available given the current user and state are listed in the operations of the Request resource.
Traveler actions
* submit: initiate the approval workflow.
* recall: get back the Request, usually to modify the content.
* cancel: cancel the Request and attached itineraries.
* close: archive the Request.
* reopen: get back an archived Request.
Non traveler actions (Approver / Processor / External Validation / TMC Agent)
approve: move the Request to the next approval step.sendback: reject the Request and send back to the traveler.
URI Template
POST {datacenter}/travelrequest/v4/requests/{requestUuid}/{action}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
requestUuid |
string |
- | Required The unique identifier of the Request. |
action |
string |
- | Required The state transition to be executed. Supported values: submit, approve, recall, sendback, cancel, close, or reopen |
comment |
string |
- | Only works with when the workflow action is sendback. This comment is visible wherever Request comments are available to the employee, approver, and/or Request administrator. |
userId |
string |
- | The unique identifier of the user performing the status transition. Required when connecting with a Company token for traveler actions only. If empty, a 400 missingRequiredParam error code will be displayed. For non traveler actions, if not provided, "System, Concur" will be displayed in the Audit Trail of the Request. |
companyID |
string |
- | The unique identifier of the company. |
Payload
None, except when the workflow action is sendback where an optional comment may be submitted
{ "comment" : "My Comment" }
This comment is visible wherever Request comments are available to the employee, approver, and/or Request administrator.
HTTP Response
v4 Endpoints Workflow - HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Request - The Request having {requestUuid} as unique identifier.
Example
HTTP Request
POST https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B/submit
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B",
"id": "053A479B3C9DD847B02A203C657AE26B",
"approvalStatus": {
"code": "SUBMITTED",
"name": "Submitted & Pending Approval"
},
"approved": false,
"businessPurpose": "Trip to Lyon for company training - Modification of dates and Cost center + Custom Field",
"canceledPostApproval": false,
"closed": false,
"creationDate": "2018-05-25T09:17:25.000Z",
"custom1": {
"value": "Training part of IT Service"
},
"custom2": {
"code": "CEN1",
"value": "54F0CBD8833CB348BD45A6C7C621C951"
},
"custom3": {
"code": "CEN1PRO2",
"value": "441D6FC50766A044ACC07FF780F1BAD9"
},
"custom4": {
"code": "TRAINING",
"value": "3F54AE68BA66EF49A5984E5197202A4D"
},
"endDate": "2018-07-09",
"endTime": "19:00",
"everSentBack": false,
"expenses": [
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/47C8AD9E382B5143BB54DC3090577C60",
"id": "47C8AD9E382B5143BB54DC3090577C60",
"template": "https://us.api.concursolutions.com/travelrequest/v4/expenses/{id}"
}
],
"lastModified": "2018-05-25T09:38:02.000Z",
"mainDestination": {
"countryCode": "FR",
"countrySubDivisionCode": "FR-69",
"city": "Lyon, FRANCE",
"name": "Lyon, FRANCE"
},
"name": "Company Training - JULY 2018",
"owner": {
"firstName": "John",
"id": "c0d9894b-98e2-48d5-86f9-1decde90dd15",
"lastName": "Doe"
},
"pendingApproval": true,
"policy": {
"id": "F4C8BD31CA9D4D6292795BE687EB9B2A"
},
"requestId": "333X",
"startDate": "2018-07-07",
"startTime": "06:15",
"submitDate": "2018-05-25T09:38:02.000Z",
"totalApprovedAmount": {
"value": 123.56,
"currency": "USD"
},
"totalPostedAmount": {
"value": 123.56,
"currency": "USD"
},
"totalRemainingAmount": {
"value": 123.56,
"currency": "USD"
},
"travelAgency": {
"href": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/2EC038D7C3CBBE4ABA0914425064D34F",
"id": "2EC038D7C3CBBE4ABA0914425064D34F",
"template": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/{id}"
},
"operations": [
{
"rel": "recall",
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B/recall"
},
{
"rel": "cancel",
"href": "https://us.api.concursolutions.com/travelrequest/v4/requests/053A479B3C9DD847B02A203C657AE26B/cancel"
}
]
}
Request v4 - Expected Expense Resources
Menu
- Getting Started
- Request
- Workflow
- Expected Expense
- Request Cash Advance
- Request Policy
- Travel Agency
- Schema
- HTTP Status Codes
- Run in Postman
Expected Expense Resources
Manage expected expenses attached to a Request.
- Create a new expected expense
- Get the list of expected expenses attached to a Request
- Get the content of an expected expense
- Update the content of an expected expense
- Delete an expected expense from the Request
- Get the list of comments for an existing expected expense
Create a new expected expense
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
POST {datacenter}/travelrequest/v4/requests/{requestUuid}/expenses
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
requestUuid |
string |
- | Required The unique identifier of the Request to which the expected expense is attached. |
userId |
string |
- | The unique identifier of the user performing the expected expense creation. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed. |
Payload
HTTP Response
v4 Expected Expense - HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Expected Expense - The created expected expense.
Example
HTTP Request
POST https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/expenses
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
"allocations": [
{
"allocationAmount": {
"currency": "USD",
"value": 122.38
},
"approvedAmount": {
"currency": "USD",
"value": 122.38
},
"percentEdited": false,
"percentage": 0,
"postedAmount": {
"currency": "USD",
"value": 122.38
},
"systemAllocation": false
}
],
"approvedAmount": {
"currency": "USD",
"value": 122.38
},
"businessPurpose": "additional punctual trip to South of France",
"exchangeRate": {
"operation": "MULTIPLY",
"value": 1
},
"expenseType": {
"id": "RAILF",
"name": "Train"
},
"lastComment": "",
"location": {
"id": "A168CDBA58AE42868961BC00278A91B3",
"countryCode": "FR",
"countrySubDivisionCode": "FR-75",
"city": "Paris",
"name": "Charles De Gaulle Intl"
},
"postedAmount": {
"currency": "USD",
"value": 122.38
},
"remainingAmount": {
"currency": "USD",
"value": 122.38
},
"transactionAmount": {
"currency": "USD",
"value": 122.38
},
"transactionDate": "2018-07-18T00:00:00Z",
"tripData": {
"agencyBooked": false,
"legs": [
{
"class": {
"code": "1ST",
"value": "05F71FA4ED235D479C6C7039F397DA79"
},
"endLocation": {
"countryCode": "FR",
"locationCode": "FRNCE",
"city": "Nice",
"name": "Cote D Azur"
},
"returnLeg": false,
"startDate": "2018-07-18",
"startLocation": {
"countryCode": "FR",
"locationCode": "FRCDG",
"city": "Paris",
"name": "ROISSY"
},
"startTime": "21:00",
"startLocationDetail": "none"
}
],
"segmentType": {
"category": "REQ_SEG_RAILF",
"code": "RAILF"
},
"selfBooked": false,
"tripType": "ONE_WAY"
}
}
HTTP Response
201 Created
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/0465224E14C23D4F8C2BC79A9D694BDD",
"id": "0465224E14C23D4F8C2BC79A9D694BDD",
"allocations": [
{
"allocationAmount": {
"value": 122.38,
"currency": "USD"
},
"approvedAmount": {
"value": 122.38,
"currency": "USD"
},
"allocationId": "28E1B1F50253CD47BE002DA7B2C218EE",
"postedAmount": {
"value": 122.38,
"currency": "USD"
},
"expenseId": "0465224E14C23D4F8C2BC79A9D694BDD",
"percentEdited": false,
"systemAllocation": true,
"percentage": 100
}
],
"approvedAmount": {
"value": 122.38,
"currency": "USD"
},
"exchangeRate": {
"value": 1,
"operation": "MULTIPLY"
},
"expenseType": {
"id": "TRAIN",
"name": "Train"
},
"postedAmount": {
"value": 122.38,
"currency": "USD"
},
"remainingAmount": {
"value": 122.38,
"currency": "USD"
},
"transactionAmount": {
"value": 122.38,
"currency": "USD"
},
"transactionDate": "2018-07-18T00:00:00.000Z",
"tripData": {
"agencyBooked": false,
"selfBooked": false,
"tripType": "ONE_WAY",
"legs": [
{
"class": {
"code": "1ST",
"value": "05F71FA4ED235D479C6C7039F397DA79"
},
"endLocation": {
"id": "CE4A6DCAC4A14D08803C28F6D5CB20F0",
"countryCode": "FR",
"countrySubDivisionCode": "FR-06",
"name": "Nice",
"locationCode": "IATA_NCE",
"locationType": "STD"
},
"id": "59508E1F979B4346AC6B38677ABE6404",
"returnLeg": false,
"startDate": "2018-07-18",
"startLocation": {
"id": "A168CDBA58AE42868961BC00278A91B3",
"countryCode": "FR",
"countrySubDivisionCode": "FR-75",
"name": "Paris",
"locationCode": "IATA_CDG",
"locationType": "STD"
},
"startLocationDetail": "none",
"startTime": "21:00"
}
],
"segmentType": {
"category": "REQ_SEG_RAILF",
"code": "RAILF"
}
}
}
Get the list of expected expenses attached to a Request
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/requests/{requestUuid}/expenses
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
requestUuid |
string |
- | Required The unique identifier of the Request. |
userId |
string |
- | The unique identifier of the user viewing the expected expenses attached to a Request. If empty when using a Company token the default system user will be assumed to perform the action. |
Payload
None.
HTTP Response
v4 Expected Expense - HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Expected Expense - List of expected expenses attached to a Request.
operations - [RFC 5988] Pagination links to next/prev/first/last page.
Example
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/expenses
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
[
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1",
"id": "B5FB8991E390474E875D6FD5BB1FDAF1",
"allocations": [
{
"allocationAmount": {
"value": 324.56,
"currency": "USD"
},
"approvedAmount": {
"value": 324.56,
"currency": "USD"
},
"allocationId": "79249903DC18464AAAD61062EA383BD4",
"postedAmount": {
"value": 324.56,
"currency": "USD"
},
"expenseId": "B5FB8991E390474E875D6FD5BB1FDAF1",
"percentEdited": false,
"systemAllocation": true,
"percentage": 100
}
],
"approvedAmount": {
"value": 324.56,
"currency": "USD"
},
"exchangeRate": {
"value": 1,
"operation": "MULTIPLY"
},
"expenseType": {
"id": "AIRFR",
"name": "Airfare"
},
"postedAmount": {
"value": 324.56,
"currency": "USD"
},
"remainingAmount": {
"value": 324.56,
"currency": "USD"
},
"transactionAmount": {
"value": 324.56,
"currency": "USD"
},
"transactionDate": "2018-07-15T00:00:00.000Z",
"tripData": {
"agencyBooked": true,
"selfBooked": false,
"tripType": "ROUND_TRIP",
"legs": [
{
"class": {
"code": "1ST",
"value": "05F71FA4ED235D479C6C7039F397DA79"
},
"endLocation": {
"id": "4A33695120254EEC9261B24993DD413B",
"countryCode": "DE",
"countrySubDivisionCode": "DE-BE",
"city": "Berlin",
"iataCode": "BER",
"name": "Berlin(Alls)"
},
"id": "B0F356643B38BC419AFE60E050BB79A4",
"returnLeg": false,
"startDate": "2018-07-15",
"startLocation": {
"id": "A168CDBA58AE42868961BC00278A91B3",
"countryCode": "FR",
"countrySubDivisionCode": "FR-75",
"city": "Paris",
"iataCode": "CDG",
"name": "Charles De Gaulle Intl"
},
"startTime": "08:00"
},
{
"endLocation": {
"id": "A168CDBA58AE42868961BC00278A91B3",
"countryCode": "FR",
"countrySubDivisionCode": "FR-75",
"city": "Paris",
"iataCode": "CDG",
"name": "Charles De Gaulle Intl"
},
"id": "345475D42A53D948A6D60181759683E8",
"returnLeg": true,
"startDate": "2018-07-17",
"startLocation": {
"id": "4A33695120254EEC9261B24993DD413B",
"countryCode": "DE",
"countrySubDivisionCode": "DE-BE",
"city": "Berlin",
"iataCode": "BER",
"name": "Berlin(Alls)"
},
"startTime": "17:00"
}
],
"segmentType": {
"category": "REQ_SEG_AIRFR",
"code": "AIRFR"
}
}
},
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/D65BDBD5D980F6498D67A92B06A457B0",
"id": "D65BDBD5D980F6498D67A92B06A457B0",
"allocations": [
{
"allocationAmount": {
"value": 90,
"currency": "USD"
},
"approvedAmount": {
"value": 90,
"currency": "USD"
},
"allocationId": "FCAA998834A24949B01AC3C1D56AF4E3",
"postedAmount": {
"value": 90,
"currency": "USD"
},
"expenseId": "D65BDBD5D980F6498D67A92B06A457B0",
"percentEdited": false,
"systemAllocation": true,
"percentage": 100
}
],
"approvedAmount": {
"value": 90,
"currency": "USD"
},
"businessPurpose": "Airport to Office after arrival and before departure",
"exchangeRate": {
"value": 1,
"operation": "MULTIPLY"
},
"expenseType": {
"id": "TAXIX",
"name": "Taxi"
},
"location": {
"id": "34AB34319377456B95F5C2815CC72766",
"countryCode": "DE",
"countrySubDivisionCode": "DE-BER",
"city": "Berlin, GERMANY",
"name": "Berlin, GERMANY"
},
"postedAmount": {
"value": 90,
"currency": "USD"
},
"remainingAmount": {
"value": 90,
"currency": "USD"
},
"transactionAmount": {
"value": 90,
"currency": "USD"
},
"transactionDate": "2018-07-17T00:00:00.000Z"
},
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/C286A46A2DDF984EA28E41CEA278667D",
"id": "C286A46A2DDF984EA28E41CEA278667D",
"allocations": [
{
"allocationAmount": {
"value": 80,
"currency": "USD"
},
"approvedAmount": {
"value": 80,
"currency": "USD"
},
"allocationId": "780B3FA5B83EC24F922EBE7B5D4AED63",
"postedAmount": {
"value": 80,
"currency": "USD"
},
"expenseId": "C286A46A2DDF984EA28E41CEA278667D",
"percentEdited": false,
"systemAllocation": true,
"percentage": 100
}
],
"approvedAmount": {
"value": 80,
"currency": "USD"
},
"businessPurpose": "Estimated costs for 2 dinners in Berlin",
"exchangeRate": {
"value": 1,
"operation": "MULTIPLY"
},
"expenseType": {
"id": "DINNR",
"name": "Dinner"
},
"location": {
"id": "34AB34319377456B95F5C2815CC72766",
"countryCode": "DE",
"countrySubDivisionCode": "DE-BER",
"city": "Berlin, GERMANY",
"name": "Berlin, GERMANY"
},
"postedAmount": {
"value": 80,
"currency": "USD"
},
"remainingAmount": {
"value": 80,
"currency": "USD"
},
"transactionAmount": {
"value": 80,
"currency": "USD"
},
"transactionDate": "2018-07-17T00:00:00.000Z"
}
]
Get the content of an expected expense
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/expenses/{expenseUuid}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
expenseUuid |
string |
- | Required The unique identifier of the expected expense. |
userId |
string |
- | The unique identifier of the user viewing the expected expense. If empty when using a Company token the default system user will be assumed to perform the action. |
Payload
None.
HTTP Response
v4 Expected Expense - HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Expected Expense - The expected expense having {expenseUuid} as unique identifier.
Example 1 - for a Request segment
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1",
"id": "B5FB8991E390474E875D6FD5BB1FDAF1",
"allocations": [
{
"allocationAmount": {
"value": 324.56,
"currency": "USD"
},
"approvedAmount": {
"value": 324.56,
"currency": "USD"
},
"allocationId": "79249903DC18464AAAD61062EA383BD4",
"postedAmount": {
"value": 324.56,
"currency": "USD"
},
"expenseId": "B5FB8991E390474E875D6FD5BB1FDAF1",
"percentEdited": false,
"systemAllocation": true,
"percentage": 100
}
],
"approvedAmount": {
"value": 324.56,
"currency": "USD"
},
"comments": {
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/2F9FB5CE3AC2C74C9AC3D4AB3A83C0DA/comments",
"id": "2F9FB5CE3AC2C74C9AC3D4AB3A83C0DA",
"template": "http://us.api.concursolutions.com/travelrequest/v4/expenses/{id}/comments"
},
"exchangeRate": {
"value": 1,
"operation": "MULTIPLY"
},
"expenseType": {
"id": "AIRFR",
"name": "Airfare"
},
"parentRequest": {
"href": "https://us.api.concursolutions.com/travelrequest/v4/request/224AF3CDCC2A5244A37C72FA5770C6F2",
"id": "224AF3CDCC2A5244A37C72FA5770C6F2",
"template": "http://us.api.concursolutions.com/travelrequest/v4/request/{requestUuid}"
},
"postedAmount": {
"value": 324.56,
"currency": "USD"
},
"remainingAmount": {
"value": 324.56,
"currency": "USD"
},
"transactionAmount": {
"value": 324.56,
"currency": "USD"
},
"transactionDate": "2018-07-15T00:00:00.000Z",
"tripData": {
"agencyBooked": true,
"selfBooked": false,
"tripType": "ROUND_TRIP",
"legs": [
{
"class": {
"code": "1ST",
"value": "05F71FA4ED235D479C6C7039F397DA79"
},
"endLocation": {
"id": "4A33695120254EEC9261B24993DD413B",
"countryCode": "DE",
"countrySubDivisionCode": "DE-BE",
"city": "Berlin",
"iataCode": "BER",
"name": "Berlin(Alls)"
},
"id": "B0F356643B38BC419AFE60E050BB79A4",
"returnLeg": false,
"startDate": "2018-07-15",
"startLocation": {
"id": "A168CDBA58AE42868961BC00278A91B3",
"countryCode": "FR",
"countrySubDivisionCode": "FR-75",
"city": "Paris",
"iataCode": "CDG",
"name": "Charles De Gaulle Intl"
},
"startTime": "08:00"
},
{
"endLocation": {
"id": "A168CDBA58AE42868961BC00278A91B3",
"countryCode": "FR",
"countrySubDivisionCode": "FR-75",
"city": "Paris",
"iataCode": "CDG",
"name": "Charles De Gaulle Intl"
},
"id": "345475D42A53D948A6D60181759683E8",
"returnLeg": true,
"startDate": "2018-07-17",
"startLocation": {
"id": "4A33695120254EEC9261B24993DD413B",
"countryCode": "DE",
"countrySubDivisionCode": "DE-BE",
"city": "Berlin",
"iataCode": "BER",
"name": "Berlin(Alls)"
},
"startTime": "17:00"
}
],
"segmentType": {
"category": "REQ_SEG_AIRFR",
"code": "AIRFR"
}
}
}
Example 2 - for a Request expected expense
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/expenses/C286A46A2DDF984EA28E41CEA278667D
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/C286A46A2DDF984EA28E41CEA278667D",
"id": "C286A46A2DDF984EA28E41CEA278667D",
"allocations": [
{
"allocationAmount": {
"value": 80,
"currency": "USD"
},
"approvedAmount": {
"value": 80,
"currency": "USD"
},
"allocationId": "780B3FA5B83EC24F922EBE7B5D4AED63",
"postedAmount": {
"value": 80,
"currency": "USD"
},
"expenseId": "C286A46A2DDF984EA28E41CEA278667D",
"percentEdited": false,
"systemAllocation": true,
"percentage": 100
}
],
"approvedAmount": {
"value": 80,
"currency": "USD"
},
"businessPurpose": "Estimated costs for 2 dinners in Berlin",
"exchangeRate": {
"value": 1,
"operation": "MULTIPLY"
},
"expenseType": {
"id": "DINNR",
"name": "Dinner"
},
"location": {
"id": "34AB34319377456B95F5C2815CC72766",
"countryCode": "DE",
"countrySubDivisionCode": "DE-BER",
"city": "Berlin, GERMANY",
"name": "Berlin, GERMANY"
},
"parentRequest": {
"href": "https://us.api.concursolutions.com/travelrequest/v4/request/224AF3CDCC2A5244A37C72FA5770C6F2",
"id": "224AF3CDCC2A5244A37C72FA5770C6F2",
"template": "http://us.api.concursolutions.com/travelrequest/v4/request/{requestUuid}"
},
"postedAmount": {
"value": 80,
"currency": "USD"
},
"remainingAmount": {
"value": 80,
"currency": "USD"
},
"transactionAmount": {
"value": 80,
"currency": "USD"
},
"transactionDate": "2018-07-17T00:00:00.000Z"
}
Update the content of an expected expense
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
PUT {datacenter}/travelrequest/v4/expenses/{expenseUuid}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
expenseUuid |
string |
- | Required The unique identifier of the expected expense to update. |
userId |
string |
- | The unique identifier of the user performing the expected expense update. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed. |
Payload
HTTP Response
v4 Expected Expense - HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Expected Expense - The expected expense having {expenseUuid} as unique identifier after update.
Example
HTTP Request
PUT https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
{
"id": "B5FB8991E390474E875D6FD5BB1FDAF1",
"allocations": [
{
"allocationAmount": {
"value": 432.45,
"currency": "USD"
},
"approvedAmount": {
"value": 432.45,
"currency": "USD"
},
"allocationId": "79249903DC18464AAAD61062EA383BD4",
"postedAmount": {
"value": 432.45,
"currency": "USD"
},
"expenseId": "B5FB8991E390474E875D6FD5BB1FDAF1",
"percentEdited": false,
"systemAllocation": true,
"percentage": 100
}
],
"approvedAmount": {
"value": 432.45,
"currency": "USD"
},
"exchangeRate": {
"value": 1,
"operation": "MULTIPLY"
},
"expenseType": {
"id": "AIRFR",
"name": "Airfare"
},
"postedAmount": {
"value": 432.45,
"currency": "USD"
},
"remainingAmount": {
"value": 432.45,
"currency": "USD"
},
"transactionAmount": {
"value": 432.45,
"currency": "USD"
},
"transactionDate": "2018-07-16T00:00:00.000Z",
"tripData": {
"agencyBooked": true,
"selfBooked": false,
"tripType": "ROUND_TRIP",
"legs": [
{
"class": {
"code": "1ST",
"value": "05F71FA4ED235D479C6C7039F397DA79"
},
"endLocation": {
"countryCode": "DE",
"city": "Berlin",
"iataCode": "BER",
"name": "Berlin(Alls)"
},
"id": "B0F356643B38BC419AFE60E050BB79A4",
"returnLeg": false,
"startDate": "2018-07-16",
"startLocation": {
"countryCode": "FR",
"city": "Paris",
"iataCode": "CDG",
"name": "Charles De Gaulle Intl"
},
"startTime": "07:00"
},
{
"endLocation": {
"countryCode": "FR",
"city": "Paris",
"iataCode": "CDG",
"name": "Charles De Gaulle Intl"
},
"id": "345475D42A53D948A6D60181759683E8",
"returnLeg": true,
"startDate": "2018-07-18",
"startLocation": {
"countryCode": "DE",
"city": "Berlin",
"iataCode": "BER",
"name": "Berlin(Alls)"
},
"startTime": "18:00"
}
],
"segmentType": {
"category": "REQ_SEG_AIRFR",
"code": "AIRFR"
}
}
}
HTTP Response
200 OK
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1",
"id": "B5FB8991E390474E875D6FD5BB1FDAF1",
"allocations": [
{
"allocationAmount": {
"value": 432.45,
"currency": "USD"
},
"approvedAmount": {
"value": 432.45,
"currency": "USD"
},
"allocationId": "79249903DC18464AAAD61062EA383BD4",
"postedAmount": {
"value": 432.45,
"currency": "USD"
},
"expenseId": "B5FB8991E390474E875D6FD5BB1FDAF1",
"percentEdited": false,
"systemAllocation": true,
"percentage": 100
}
],
"approvedAmount": {
"value": 432.45,
"currency": "USD"
},
"exchangeRate": {
"value": 1,
"operation": "MULTIPLY"
},
"expenseType": {
"id": "AIRFR",
"name": "Airfare"
},
"parentRequest": {
"href": "https://us.api.concursolutions.com/travelrequest/v4/request/224AF3CDCC2A5244A37C72FA5770C6F2",
"id": "224AF3CDCC2A5244A37C72FA5770C6F2",
"template": "http://us.api.concursolutions.com/travelrequest/v4/request/{requestUuid}"
},
"postedAmount": {
"value": 432.45,
"currency": "USD"
},
"remainingAmount": {
"value": 432.45,
"currency": "USD"
},
"transactionAmount": {
"value": 432.45,
"currency": "USD"
},
"transactionDate": "2018-07-16T00:00:00.000Z",
"tripData": {
"agencyBooked": true,
"selfBooked": false,
"tripType": "ROUND_TRIP",
"legs": [
{
"class": {
"code": "1ST",
"value": "05F71FA4ED235D479C6C7039F397DA79"
},
"endLocation": {
"id": "4A33695120254EEC9261B24993DD413B",
"countryCode": "DE",
"countrySubDivisionCode": "DE-BE",
"city": "Berlin",
"iataCode": "BER",
"name": "Berlin(Alls)"
},
"id": "B0F356643B38BC419AFE60E050BB79A4",
"returnLeg": false,
"startDate": "2018-07-16",
"startLocation": {
"id": "A168CDBA58AE42868961BC00278A91B3",
"countryCode": "FR",
"countrySubDivisionCode": "FR-75",
"city": "Paris",
"iataCode": "CDG",
"name": "Charles De Gaulle Intl"
},
"startTime": "07:00"
},
{
"endLocation": {
"id": "A168CDBA58AE42868961BC00278A91B3",
"countryCode": "FR",
"countrySubDivisionCode": "FR-75",
"city": "Paris",
"iataCode": "CDG",
"name": "Charles De Gaulle Intl"
},
"id": "345475D42A53D948A6D60181759683E8",
"returnLeg": true,
"startDate": "2018-07-18",
"startLocation": {
"id": "4A33695120254EEC9261B24993DD413B",
"countryCode": "DE",
"countrySubDivisionCode": "DE-BE",
"city": "Berlin",
"iataCode": "BER",
"name": "Berlin(Alls)"
},
"startTime": "18:00"
}
],
"segmentType": {
"category": "REQ_SEG_AIRFR",
"code": "AIRFR"
}
}
}
Delete an expected expense from the Request
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
DELETE {datacenter}/travelrequest/v4/expenses/{expenseUuid}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
expenseUuid |
string |
- | Required The unique identifier of the expected expense to delete. |
userId |
string |
- | The unique identifier of the user performing the deletion of the expected expense. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed. |
Payload
None.
HTTP Response
v4 Expected Expense - HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
None.
Example
HTTP Request
DELETE https://us.api.concursolutions.com/travelrequest/v4/expenses/D65BDBD5D980F6498D67A92B06A457B0
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
true
Get the list of comments for an existing expected expense
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/expenses/{expenseUuid}/comments
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
expenseUuid |
string |
- | Required The unique identifier of the expected expense. |
userId |
string |
- | The unique identifier of the user getting the content of the comments. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error code will be displayed. |
Payload
None.
HTTP Response
v4 Expected Expense - HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Example
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/expenses/B5FB8991E390474E875D6FD5BB1FDAF1/comments
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
[
{
"author": {
"firstName": "Steve",
"lastName": "Smith"
},
"creationDateTime": "2019-07-12T11:51:14.000Z",
"isLatest": true,
"value": "I have reviewed the required amount, too expensive. You are allowed to a maximum of 100 USD for a business meal"
},
{
"author": {
"firstName": "John",
"lastName": "Doe"
},
"creationDateTime": "2019-07-12T11:11:39.000Z",
"isLatest": false,
"value": "Please review the required amount for approval"
}
]
Request v4 - Request Cash Advance Resources
Menu
- Getting Started
- Request
- Workflow
- Expected Expense
- Request Cash Advance
- Request Policy
- Travel Agency
- Schema
- HTTP Status Codes
- Run in Postman
Request Cash Advance Resources
Note: This cash advance detail endpoint is provided within the Concur Request API for feature parity purpose only. It is highly recommended to rely only on the list of cash advances link available in the Request payload response, and not on this cash advance detail URI presented below, which will be deprecated in the future.
Get the content of an existing cash advance
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/cashadvances/{cashAdvanceUuid}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
cashAdvanceUuid |
string |
- | Required The unique identifier of the cash advance. |
Payload
None.
HTTP Response
v4 Cash Advance - HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Example
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/cashadvances/{cashAdvanceUuid}
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
[
{
"amountRequested": {
"value": 1.000000,
"currency": "USD"
},
"approvalStatus": {
"code": "C_PEND",
"name": "Pending Approval"
},
"cashAdvanceId: EF3E237ACAA3C449B808BA75BDD049FA,
"exchangeRate": {
"value": 1.00000000000000,
"operation": "MULTIPLY"
},
"requestDate": 2019-11-14:T10:39:00.000Z"
}
]
Request v4 - Request Policy Resources
Menu
- Getting Started
- Request
- Workflow
- Expected Expense
- Request Cash Advance
- Request Policy
- Travel Agency
- Schema
- HTTP Status Codes
- Run in Postman
Request Policy Resources
Get the list of existing Request policies for a given user
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/userpolicies
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
userId |
string |
- | The unique identifier of the user for whom the list of Request policies will be retrieved. Required when connecting with a Company token. If empty, a 400 missingRequiredParam error. |
Payload
None.
HTTP Response
v4 Endpoinrts Policy - HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Example
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/userpolicies
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
[
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/userpolicies/F4C8BD31CA9D4D6292795BE687EB9B2A",
"id": "F4C8BD31CA9D4D6292795BE687EB9B2A",
"name": "Internal training Request policy"
},
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/userpolicies/F10E6059B5A14A4C80327FE387491026",
"id": "F10E6059B5A14A4C80327FE387491026",
"name": "Client meeting Request policy"
}
]
Request v4 - Travel Agency Resources
Menu
- Getting Started
- Request
- Workflow
- Expected Expense
- Request Cash Advance
- Request Policy
- Travel Agency
- Schema
- HTTP Status Codes
- Run in Postman
Travel Agency Resources
Manage the configuration for Travel Agencies integrated with Concur Request.
Get the description of a Travel Agency
Scopes
travelrequest.write - Refer to Scope Usage for full details.
HTTP Request
URI Template
GET {datacenter}/travelrequest/v4/travelagencies/{agencyUuid}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
agencyUuid |
string |
- | Required The unique identifier of the Travel Agency. |
Payload
None
HTTP Response
v4 Travel Agency - HTTP Status Codes
To learn more about response HTTP status codes for this API see Travel Request v4 - HTTP Status Codes.
Payload
Example
HTTP Request
GET https://us.api.concursolutions.com/travelrequest/v4/travelagencies/86B720AF168F1C4CA52E37AC710E897B
Accept: application/json
Authorization: Bearer {token}
HTTP Response
200 OK
{
"href": "https://us.api.concursolutions.com/travelrequest/v4/travelagencies/86B720AF168F1C4CA52E37AC710E897B",
"id": "2EC038D7C3CBBE4ABA0914425064D34F",
"emailAddress": "agency-email@agencyname.com",
"name": "myCompanyAgency"
}
Request v4 - Endpoints - Schemas
Menu
- Getting Started
- Request
- Workflow
- Expected Expense
- Request Cash Advance
- Request Policy
- Travel Agency
- Schema
- HTTP Status Codes
- Run in Postman
Schema
- Request
- Amount
- ApprovalStatus
- Cash Advance
- Cash Advance Approval Status
- Comments
- Customfield
- Employee
- Exceptions
- Exception Source
- Link
- List of Request
- List of Request Policies
- Location
- ResourceLink
- RequestLink
- Request Policy
- Request Type
- Expected Expense
- Allocation
- Exchange Rate
- Expense Type
- List Item Field
- Segment Leg
- Segment Type
- Travel Agency
- Travel Allowance
- Trip Data
- Vendor
Request
| Name | Type | Format | Description |
|---|---|---|---|
approvalLimitDate |
timestamp |
[RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' |
The date by which the Request must be approved. This element appears only when integrated with Concur Travel. |
approvalStatus |
object |
Approval Status |
The approval status of the Request. |
approved |
boolean |
- | Indicates whether this Request is approved. |
approver |
object |
Employee |
The approver to whom the Request was sent. |
authorizedDate |
timestamp |
[RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' |
For approved Request, the date at which the approval process was completed. |
businessPurpose |
string |
- | The business purpose of the Request. |
canceledPostApproval |
boolean |
- | Indicates whether this Request was canceledPostApproval. |
cashAdvances |
object |
ResourceLink |
The list of cash advances for this Request. |
closed |
boolean |
- | Indicates whether this Request is closed. |
comment |
string |
- | The last comment attached to this Request. |
comments |
object |
ResourceLink |
The list of comments for this Request. |
creationDate |
timestamp |
[RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' |
The date the Request was created. |
custom1 to custom20 |
object |
CustomField |
The details from the Custom fields. These fields may not have data, depending on the configuration. |
endDate |
date |
[ISO 8601] yyyy-MM-dd |
The end date of the Request. |
endTime |
time |
[ISO 8601] yyyy-MM-dd |
The end time of the Request. |
everSentBack |
boolean |
- | Indicates whether the Request has ever been sent back to the employee. |
exceptions |
object |
ResourceLink |
The list of exceptions that have been raised to this Request. |
expenses |
array |
ResourceLink |
Expected expenses attached to this Request. |
extensionOf |
object |
RequestLink |
The Request that this Request is an extension of, or addendum to. |
highestExceptionLevel |
string |
- | The highest level of exception contained in this Request. Supported values: WARNING, ERROR, and NONE |
href |
string |
[RFC 3986] | Hyperlink to the resource for this Request. |
id |
string |
- | The unique identifier of the Request. |
lastModified |
timestamp |
[RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' |
The date the Request was last modified. |
mainDestination |
object |
Location |
The main destination of the Request. |
name |
string |
- | The name of the Request. |
owner |
object |
Employee |
The employee who owns the Request. |
pendingApproval |
boolean |
- | Indicates whether this Request is pending approval. |
policy |
object |
ResourceLink |
The policy that applies to the Request. |
requestId |
string |
4 to 6 alphanumeric characters | The public key of the Request (unique per customer). |
startDate |
date |
[ISO 8601] yyyy-MM-dd |
The start date of the Request. |
startTime |
time |
[ISO 8601] yyyy-MM-dd |
The start time of the Request. |
submitDate |
timestamp |
[RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' |
The date the Request was submitted (last submit date in case of recall). |
totalApprovedAmount |
object |
Amount |
The total amount of approved expected expenses in the Request, expressed in the reimbursement currency of the employee at the time they created the Request. |
totalPostedAmount |
object |
Amount |
The total amount of the Request, expressed in the reimbursement currency of the employee at the time they created the Request. |
totalRemainingAmount |
object |
Amount |
The total amount not included in an Expense report, expressed in the reimbursement currency of the employee at the time they created the Request. |
travelAgency |
object |
ResourceLink |
The travel agency office that is managing the trip associated to this Request. |
operations |
array |
Link |
Links to operations available for the Request, depends on the current workflow status. |
type |
object |
RequestType |
The type of the Request, inherited from the Request Policy Type. |
Amount
| Name | Type | Format | Description |
|---|---|---|---|
value |
number |
- | Required The amount in the defined currency. |
currency |
string |
[ISO 4217:2015] | Required The 3-letter ISO 4217 code for the currency in which the amount is expressed. |
Approval Status
| Name | Type | Format | Description |
|---|---|---|---|
code |
string |
- | The code for the approval status of the Request. Supported values: NOT_SUBMITTED, SUBMITTED, APPROVED, CANCELED, or SENTBACK |
name |
string |
- | The approval status of the Request in the current user's language. |
Cash Advance
| Name | Type | Format | Description |
|---|---|---|---|
amountRequested |
object |
Amount |
The amount of the cash advance in the Request, expressed in the reimbursement currency of the employee at the time they created the cash advance. |
approvalStatus |
object |
Cash Advance Approval Status |
The approval status of the cash advance. |
cashAdvanceId |
string |
- | The unique identifier of the cash advance. |
comment |
string |
- | The last comment related to this cash advance. |
exchangeRate |
object |
Exchange Rate |
The exchange rate that applies to the cash advance. |
issueDate |
timestamp |
[RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS |
The date the cash advance was issued. |
requestDate |
timestamp |
[RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS |
The date the cash advance was submitted (last submit date in case of recall). |
Cash Advance Approval Status
| Name | Type | Format | Description |
|---|---|---|---|
code |
string |
- | The code for the approval status of the cash advance. Supported values: C_PEND, C_APPR, C_COMP, C_FILE, C_ISSU, C_NISU, C_NOTF, C_PECA, or C_REJE |
name |
string |
- | The approval status of the cash advance in the current user's language. |
Comments
| Name | Type | Format | Description |
|---|---|---|---|
author |
object |
Employee |
The employee who has created the comment in the expected expense. |
creationDate |
timestamp |
[RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS |
Creation date of the comment. |
isLatest |
boolean |
- | If true, the comment has been edited since the last workflow transition. |
value |
string |
- | The value of the comment. |
CustomField
| Name | Type | Format | Description |
|---|---|---|---|
code |
string |
- | The short code for the list item. For non-list fields, this value will be blank. |
value |
string |
- | The value of the non-list item. For list fields, this is the unique id of the list item. |
href |
string |
- | The link to get this list item on the list service. Empty for non-list items. |
Retrieving the listItemId requires to call the List API, which is currently being worked on for externalisation. In the meantime, to fill in a custom list item for the creation of a Request or an Expected Expense, clients may use one of the following workaround:
* Use the copy down configuration feature to update custom fields from the Employee profile to the Request header, and from the Request header to the Expected expense.
* For a limited number of list items that are part of a custom field, a Request containing those values in the related custom fields may be manually created. The list item unique id will then be retrieved by calling the get detail of this Request. The same process is used for all list items values of the list.
Employee
| Name | Type | Format | Description |
|---|---|---|---|
firstName |
string |
- | The first name of the employee. |
href |
string |
[RFC 3986] | Hyperlink to the resource. |
id |
string |
[RFC 4122] | Unique identifier of the related object. |
lastName |
string |
- | The last name of the employee. |
middleInitial |
string |
- | The middle initial of the employee. |
template |
string |
- | Hyperlink template to the resource. |
Exceptions
| Name | Type | Format | Description |
|---|---|---|---|
code |
string |
- | The system exception code defined for the exception. Example: BADCODE |
isBlocking |
boolean |
- | Defines whether the exception will prevent the Request from being submitted. |
level |
integer |
- | The numeric level associated with the exception. Example: 99 |
message |
string |
- | The user facing message defined for the exception. |
source |
array |
Exception source |
The source that has raised the exception. |
parameters |
map |
missingFields: array of missing field labelsmissingFieldsIds: array of missing field ids |
For missing fields exceptions, additional values giving more label and ids of the missing fields. Example : parameters : { "missingFields" : ["Request Name", "Purpose"], "missingFieldsIds" : [ "Name", "Purpose" ] } |
Exception Source
| Name | Type | Format | Description |
|---|---|---|---|
href |
string |
[RFC 3986] | Hyperlink to the resource. |
id |
string |
[RFC 4122] | Unique identifier of the source. |
type |
string |
- | Defines the type of the source. Supported values: ALLOCATION, CASH_ADVANCE, EXPENSE, and HEADER |
Link
| Name | Type | Format | Description |
|---|---|---|---|
rel |
string |
[RFC 5988] | Relation type as defined by the server. There are registered relation types listed in RFC 5988 6.2.2. Initial Registry Contents including pagination relation types of next, prev, first and last. |
href |
string |
[RFC 3986] | Hyperlink to the resource. |
List of Request
| Name | Type | Format | Description |
|---|---|---|---|
data |
array |
Request |
List of Requests in the page requested. |
operations |
array |
Link | Links to next, prev, first and last pages. |
List of Request Policies
| Name | Type | Format | Description |
|---|---|---|---|
| - | array |
Request Policy |
List of active Requests policies for a given user. |
Location
| Name | Type | Format | Description |
|---|---|---|---|
city |
string |
- | Required for all city location type (not airport, or rail station) The city name of the location. |
countryCode |
string |
[ISO 3166-1] | Required if city or name is used The ISO 3166-1 country code. |
countrySubDivisionCode |
string |
[ISO 3166-2] | The ISO 3166-2 country sub code. |
iataCode |
string |
- | The IATA code of an airport location. |
id |
string |
- | The id of the location. |
latitude |
number |
- | The latitude of the location. |
locationCode |
string |
- | Required if rail is used The code of the location. |
locationType |
string |
- | Required if rail is used The type of the location. |
longitude |
number |
- | The longitude of the location. |
name |
string |
- | Required for rail station The name of the location. Always provide the countryCode value in addition to the name. |
Below are the different node expected in the POST endpoints by location type (City, Rail station, or Airport) - example for endLocation field:
Airport
json
"endLocation": {
"city": "Moscow",
"name": "Sheremetyevo",
"countryCode": "RU",
"iataCode": "SOV"
}
City
json
"endLocation": {
"city": "Vienna",
"countryCode": "AT"
}
Rail station (locationCode exists, locationType depends of rail provider)
json
"endLocation": {
"name": "MARSEILLE ST CHARLES",
"countryCode": "FR",
"locationCode": "FRMSC",
"locationType": "RAIL_2C"
}
Location types for Rail :
| Location Type | Railway company |
|---|---|
RAIL_0Z |
Swiss Federal Railways |
RAIL_2A |
Deutsche Bahn AG |
RAIL_2C |
SNCF |
RAIL_2H |
Thalys International |
RAIL_2R |
VIA Rail Canada Inc. |
RAIL_2V |
Amtrak |
RAIL_9F |
Eurostar International Limited |
RAIL_XH |
China Railway |
RAIL_Z0 |
UK Rail |
STD |
Standard rail locations |
ResourceLink
| Name | Type | Format | Description |
|---|---|---|---|
href |
string |
[RFC 3986] | Hyperlink to the resource. |
id |
string |
[RFC 4122] | Unique identifier of the related object. |
template |
string |
- | Hyperlink template to the resource. |
RequestLink
| Name | Type | Format | Description |
|---|---|---|---|
requestId |
string |
4 to 6 alphanumeric characters | The public key of the Request (unique per customer). |
Request Policy
| Name | Type | Format | Description |
|---|---|---|---|
href |
string |
[RFC 3986] | Hyperlink to the resource for this Request policy. |
id |
string |
- | The Request policy unique identifier. |
name |
string |
- | The name of the Request policy. |
Request Type
| Name | Type | Format | Description |
|---|---|---|---|
code |
string |
- | The code of the type inherited from the Request Policy type. |
label |
string |
- | The label of the type inherited from the Request Policy Type. |
Expected Expense
| Name | Type | Format | Description |
|---|---|---|---|
allocations |
object |
Allocation |
The details of the allocations for this expected expense. |
approvedAmount |
object |
Amount |
The approved amount of the expected expense entry, in the transaction currency of the Request. |
budgetAccrualDate |
timestamp |
[RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' |
The date to determine which budgets are affected. |
businessPurpose |
string |
- | The business purpose of the Request entry. |
comments |
object |
ResourceLink |
The list of comments for this expected expense. |
custom1 to custom40 |
object |
CustomField |
The details from the Custom fields. These fields may not have data, depending on the configuration. |
exchangeRate |
object |
Exchange Rate |
The exchange rate that applies to the entry. |
expenseType |
object |
Expense Type |
The expense type of the entry. Required for expected expenses, automatically set for segments depending on the SegmentType code. |
href |
string |
[RFC 3986] | Hyperlink to the resource for this Request entry. |
id |
string |
- | The unique identifier of the expected expense entry. |
lastComment |
string |
- | The last comment (most recent) of the expected expense entry. |
lastModifiedDate |
timestamp |
[RFC 3339] | The date when this expected expense was last modified. |
location |
object |
Location |
The location of the expected expense entry. |
orgUnit1 to orgUnit6 |
object |
Amount |
The details from the Custom fields. These fields may not have data, depending on the configuration. |
postedAmount |
object |
Amount |
The posted amount of the expected expense entry, in the transaction currency of the Request. |
parentRequest |
object |
ResourceLink |
The parent Request of the expected expense. |
remainingAmount |
object |
Amount |
The remaining amount of the expected expense entry, in the transaction currency of the Request. |
source |
enum |
- | The source that created the expected expense. Supported values: CASH_ADVANCE or TRAVEL_ALLOWANCE. This field will be empty in any other case |
transactionAmount |
object |
Amount |
Required The amount of the expected expense entry, in the transaction currency paid to the vendor. |
transactionDate |
timestamp |
[RFC 3339] yyyy-MM-dd'T'HH:mm:ss.SSS'Z' |
Required The date of the transaction. |
travelAllowance |
object |
Travel Allowance |
The Travel allowance. |
tripData |
object |
Trip Data |
The description of the trip. |
vendor |
object |
Vendor |
The vendor of the expected expense entry. |
Allocation
| Name | Type | Format | Description |
|---|---|---|---|
allocationAmount |
object |
Amount |
The amount of the allocation calculated with the percentage value multiplied by the transaction amount on the expected expense. This amount is given in the transaction's currency and rounded to eight digits after the decimal point. |
approvedAmount |
object |
Amount |
The amount of the allocation calculated with the percentage value multiplied by the approved amount on the expected expense. This amount is given in the user's currency and rounded to eight digits after the decimal point. |
allocationId |
string |
- | The unique allocation identifier. |
custom1 to custom20 |
object |
CustomField |
The details from the Custom fields. These fields may not have data, depending on the configuration. |
expenseId |
string |
- | The unique identifier of the expected expense associated with the allocation. |
percentEdited |
boolean |
- | Whether the allocation percent has been edited. |
percentage |
number |
- | The percentage of the total expected expense that this allocation represents. |
postedAmount |
object |
Amount |
The amount of the allocation calculated with the percentage value multiplied by the posted amount on the expected expense. This amount is given in the user's currency and rounded to eight digits after the decimal point. |
systemAllocation |
boolean |
- | Whether the allocation is a system allocation, usually hidden from the user. If displayed to the user, should be read-only. |
Exchange Rate
| Name | Type | Format | Description |
|---|---|---|---|
operation |
string |
- | Exchange rate operation. Supported values: MULTIPLY, DIVIDE |
value |
number |
- | Exchange rate value. |
Expense Type
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | Required Unique identifier of the expense type. |
name |
string |
- | Name of the expense type. |
List Item Field
| Name | Type | Format | Description |
|---|---|---|---|
code |
string |
- | The short code of the list item. |
value |
string |
- | Unique identifier of the list item. |
href |
string |
[RFC 3986] | Hyperlink to the resource for the list item. |
Segment Leg
| Name | Type | Format | Description |
|---|---|---|---|
class |
list |
List Item Field |
The booking class of the segment leg. |
classOfService |
string |
- | The class of service of the segment leg. For example, in the case of an air segment, this field would contain the one-letter booking code: Y for economy class, or F for first class. |
comment |
string |
- | Contains the last comment saved in this segment leg. |
custom1 to custom40 |
object |
CustomField |
The details from the Custom fields. These fields may not have data, depending on the configuration. |
endDate |
date |
[ISO 8601] YYYY-MM-DD |
The date of the end of this segment leg. It represents the arrival date of AIRFR and TRAIN segments, check out date for HOTEL, or drop off for CARRT. |
endLocation |
object |
ResourceLink |
The location where this segment leg arrives. For example, the arrival location for an air segment. |
endLocationDetail |
string |
- | Details about the end location. This would contain details about the name of a hotel, or some details about a car rental agency for example. |
endTime |
time |
[ISO 8601] HH:MM |
The time for the end of this segment leg. |
id |
string |
- | The unique identifier of the segment leg. |
returnLeg |
boolean |
- | Indicates whether this leg is the return leg of a round trip. In case of a ROUND_TRIP, if not explicitly set, the second segment leg will be considered as the return leg. |
startDate |
date |
[ISO 8601] YYYY-MM-DD |
The date of the beginning of this segment leg. |
startLocation |
object |
ResourceLink |
The start location of this segment leg. This would be the departure location for an air segment for example. |
startLocationDetail |
string |
- | Details about the start location. This would contain details about the name of a hotel, or some details about a car rental agency for example. |
startTime |
time |
[ISO 8601] HH:MM |
The time for the beginning of this segment leg. |
segmentLocator |
string |
- | This is the identifier for Concur Travel segments (if applicable). |
vendorName |
string |
- | Contains the vendor description of the segment leg. |
Segment Type
| Name | Type | Format | Description |
|---|---|---|---|
category |
enum |
- | Describes the category of this segment type. Supported values: REQ_SEG_AIRFR, REQ_SEG_CARRT, REQ_SEG_HOTEL, REQ_SEG_LIMOF, REQ_SEG_RAILF, REQ_SEG_TAXIF, REQ_SEG_MISC, REQ_SEG_PARKG, REQ_SEG_DININ, REQ_SEG_EVENT |
code |
string |
- | Required The code of the segment type. Supported values: AIRFR, CARRT, HOTEL, LIMOF, RAILF, TAXIF, MISC, PARKG, DININ, EVENT or custom codes |
It can be REQ_SEG_AIRFR / AIRFR for a regular air segment, or REQ_SEG_AIRFR / 10325 for a custom air segment.
Example:
{
"category": "REQ_SEG_AIRFR",
"code": "AIRFR"
}
Travel Agency
| Name | Type | Format | Description |
|---|---|---|---|
emailAddress |
string |
- | The travel agency email address. |
id |
string |
- | The travel agency unique identifier. |
name |
string |
- | The travel agency office name. |
proposalType |
string |
- | The travel agency proposal type. Supported values: CWTF, AEBT, API |
Travel Allowance
| Name | Type | Format | Description |
|---|---|---|---|
dailyTravelAllowanceId |
string |
- | The fixed daily travel allowance id associated with the expected expense. |
Trip Data
| Name | Type | Format | Description |
|---|---|---|---|
agencyBooked |
boolean |
- | If true, this travel is (or has to be) handled by a travel agency. |
legs |
list |
Segment Leg |
The list of the legs of the travel. |
tripType |
string |
- | Indicates the type of this trip. Supported values: ONE_WAY, ROUND_TRIP, or MULTI_STOPS. If not provided, will be detected from the given legs. |
segmentType |
object |
Segment Type |
Required The type of the segment. |
selfBooked |
boolean |
- | If true, this travel has been reserved by Concur Travel, or if Concur Travel has retrieved the trip information in the GDS. |
Vendor
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
- | The vendor identifier of the entry. |
name |
string |
- | The vendor description of the entry. |
Request v4 - HTTP Status Codes
Menu
- Getting Started
- Request
- Workflow
- Expected Expense
- Request Cash Advance
- Request Policy
- Travel Agency
- Schema
- HTTP Status Codes
- Run in Postman
HTTP Status Codes
| HTTP Status Code | Response Body | Description |
|---|---|---|
| 200 OK | - | Your GET request succeeded. |
| 201 Created | - | Your POST request succeeded. |
| 400 Bad Request | badParam the request has bad parameter(s) {requestName} |
The name of the request doesn't have the expected format |
| - | invalidJson invalid json structure |
An input JSON structure couldn't be parsed |
| - | invalidDate error while parsing date value {dateValue} |
A date or datetime value couldn't be parsed |
| - | invalidUuid for concur-correlationid {correlationId} |
The concur correlation id of the request is not a valid UUID |
| - | invalidUuid {requestName} |
The name of the request doesn't have the expected format |
| - | invalidLocation the location cannot be resolved, please provide either {iataCode} or {countryCode} and {cityName} |
Required location input is missing |
| - | invalidLocation the location cannot be resolved, no location found for iataCode={iataCode} |
No location found matching the iataCode provided |
| - | invalidLocation the location cannot be resolved, no city found for countryCode={countryCode} and cityName={cityName} |
No location found matching the country code and city name provided |
| - | invalidLocation the location cannot be resolved, multiple locations available for countryCode={countryCode} and cityName={cityName} |
Multiple locations found matching the country code and city name provided |
| - | invalidPolicy invalid policy id |
|
| - | listValidationError validation of list items failed |
|
| - | missingRequiredField at least 1 required field has an empty value |
A request with no value on a mandatory field has been submitted |
| - | blockingException at least 1 blocking exception |
A request with a blocking exception has been submitted |
| - | multiLegNotAllowed cannot save a multi leg, multi-leg is not enabled for this entity |
The multi leg support is not allowed for the entity |
| - | reportTemplateNotFound failed to retrieve report template |
The multi leg support is not allowed for the entity |
| - | unsupportedParam the request has unsupported parameter(s) |
Some parameter(s) of the request are not supported |
| - | missingRequiredParam the request is missing required parameter(s) |
The request is missing some required parameter(s) |
| - | companyNotFound the company for this request has not been found |
The company for this request has not been found |
| - | userNotFound user {id} not found |
The user Id for this request has not been found |
| - | invalidUuid invalid {Uuid} for the userId |
The unique identifier for this userId is not valid |
| - | - Limit must be less than or equal to 100 |
limit must be less than or equal to 100 |
| - | - Limit must be greater than or equal to 1 |
limit must be greater than or equal to 1 |
| - | - Limit must contains only digits |
Limit must contains only digits |
| 401 Unauthorized | invalidUser the request's user is invalid |
invalid or non existent authorization HTTP header |
| 403 Forbidden | permissionDenied permission denied |
User approving their own Request, or without approver/processor role |
| - | requestStatusNotApproved the Request is not approved or canceled after approval |
|
| - | userIsNotAllowed user is not allowed to access this resource |
|
| - | requestStartDateInTheFuture expense report cannot be create from an approved Request before Request start |
|
| - | publicApiNotAllowed entity is not allowed to access this resource |
|
| - | publicApiNotAllowed this resource is not public |
|
| - | CASH_ADVANCE_CANNOT_SUBMIT_AS_DELEGATE |
The cash advance cannot be submitted by the delegate. |
| - | CASH_ADVANCE_CANNOT_APPROVE_OWN_CA |
You cannot approve your own cash advance. |
| 404 Not Found | notFound resource not found |
You tried to get a non-existing request |
| 408 Request Timeout | timeOut timeout has occurred |
|
| 409 Conflict | NO_APPROVER No approver was found. |
You must identify an approver before the request moves on to the next workflow step. |
| - | NO_APPROVER_NOT_EDITABLE_STEP |
There are no approvers defined in your workflow. Contact your Expense administrator for assistance. |
| - | NO_APPROVER_CHANGE_MY_INFO |
Missing the required approver for next workflow step. You may be able to select an approver; otherwise contact your Administrator for assistance. |
| - | NO_AUTH_APPROVERS |
This request cannot be sent to the next approver. This workflow step must be approved by a specialised approver called an Authorised Approver. There are no Authorised Approvers defined. Please contact your Request administrator for assistance. |
| - | REVIEW_APPROVAL_FLOW_APPROVER |
Review approvers in the workflow. |
| - | APPROVER_CUM_REPORTOWNER |
You cannot send this request to this approver since this person created this request. |
| - | APPROVER_CUM_REPORTOWNER_EDITABLE |
Your workflow is configured such that the request would come back to the request owner during some step. Please contact your Employee Administrator to change the approvers. |
| - | INVALID_AUTH_APPROVER |
This request cannot proceed without an approver type of Authorised Approver. Select an approver who is an Authorised Approver before proceeding. |
| - | CONFIG_INVALID_NEXT_STEP |
You must identify an approver before the request moves on to the next workflow step. |
| - | STEP_EXIT_BLOCKING_BY_EXCEPTION |
One or more blocking exceptions are preventing approval submission. Resolve the exception before proceeding. |
| - | CASH_ADVANCE_SUBMIT_GENERIC |
Cash Advance Status Change: Failure |
| - | CASH_ADVANCE_SUBMIT_ALREADY_SUBMITTED |
The cash advance has already been submitted and cannot be submitted again. |
| - | CASH_ADVANCE_CONFIG_INVALID_NEXT_STEP |
Cash Advance: You must identify an approver before the request moves on to the next workflow step |
| - | CASH_ADVANCE_APPROVER_CUM_REPORTOWNER |
Cash Advance: You cannot send this request to this approver since this person created this request. |
| - | CASH_ADVANCE_APPROVER_CUM_REPORTOWNER_IS_EDITABLE_BY |
Cash Advance: Your workflow is configured such that the claim would come back to the claim owner during some step. Please contact your Employee Administrator to change the approvers. |
| - | CASH_ADVANCE_INVALID_AUTH_APPROVER |
Cash Advance: This request cannot be sent to the next approver. This workflow step must be approved by a specialised approver called an Authorised Approver. The selected approver is not an Authorised Approver. Select another approver. |
| - | CASH_ADVANCE_NO_APPROVER |
Cash Advance: You must identify an approver before the request moves on to the next workflow step. |
| - | CASH_ADVANCE_NO_APPROVER_CHANGE_MY_INFO |
Cash Advance: Missing the required approver for the next workflow step. Contact your Expense administrator for assistance. |
| - | CASH_ADVANCE_NOT_AN_APPROVER |
Cash Advance: This request cannot be sent to the next approver because the selected approver is no longer authorised to approve requests. Please select another approver. |
| - | CASH_ADVANCE_REVIEW_APPROVAL_FLOW_APPROVER |
Cash Advance: Review Approvers in the workflow. |
| 500 Internal Server Error | timeOut timeout has occurred |
|
| - | createReportError error while creating an expense report |
|
| - | internalServerError internal server error |
|
| - | associateReportError error while associating an expense report to a Request |
|
| 503 Service Unavailable | circuitBreaker Circuit Breaker is open, please try again on a different node |
The server node might be unavailable, be retrying the request you may reach a healthy node |
| - | entityOffline Entity is offline, please try again later. |
|
| - | CLIQBOOK_APPROVAL_FAILURE |
This request cannot be approved due to trip approval failure. |
| - | CLIQBOOK_APPROVAL_RETRY |
This request cannot be approved immediately. Please try again later. |
| - | CLIQBOOK_CANCEL_FAILURE |
This request cannot be cancelled due to trip cancel failure. |
Travel Profile
Travel Profile v2
The Travel Profile service consists of a set of resources that provide travel profile functionality customized in specific ways for developers, travel suppliers, and travel management companies (TMCs).
Profile v2
These web services can be used to retrieve travel profile information for a specified user, or a list of travel profile summaries.
Available to Developers, travel suppliers, and TMCs.
Loyalty Program v1
This web service can be used to update loyalty information for the user as entered in Concur.
Available to Travel suppliers and TMCs.
Company Notification v1
A subscription to a notification when any user in the Concur company changes the specified features of their Concur account or data. Currently supports notifications for the following events: Itinerary change (create or update), Travel Profile basic information change. To obtain notifications, the Concur users must grant access to their travel profile using the Web authorization flow.
Available to Travel suppliers.
User Notification v1
A subscription to a notification when the Concur user changes the specified features of their Concur account or data. Currently supports notifications for the following events: Itinerary change (create or update), or Travel Profile basic information change. This functionality is restricted to Travel Suppliers or TMCs (Travel Management Companies) who have registered with Concur. To obtain notifications, the Concur users must grant access to their travel profile using the Web authorization flow.
Available to Travel suppliers.
Configuration
Travel supplier or TMC partner applications must complete the Concur application review process before they can access production user data. Suppliers can only update Loyalty Program information for the programs that they manage. TMCs can access all the user's Travel Profile data, regardless of vendor.
Travel Profile v2 - Resource
The Travel Profile resource represents a Concur Travel profile that contains travel-related information about a user.
Operations
- Get a travel profile
- Create / Update a travel profile
- Schema
- General
- EmergencyContact
- Address
- Phone List
- Telephones
- Addresses
- NationalIDs
- DriversLicenses
- HasNoPassport
- Passports
- Visas
- EmailAddresses
- RatePreferences
- DiscountCodes
- Air
- Air Memberships
- Seat
- Rail
- Rail Membership
- Car
- Car Memberships
- Hotel
- Hotel Memberships
- CustomFields
- Roles
- Sponsors
- TSAInfo
- UnusedTickets
- SouthwestUnusedTickets
- AdvantageMemberships
- Possible Warning and Error Messages
- Get a list of travel profile summaries
Detailed descriptions of requests and responses are available in the documentation for each HTTP method.
Get a Travel Profile
This endpoint provides travel profile information for the specified user. The travel profile includes information such as the user's identity, contact information, rate preferences and discount codes, preferences by travel type, and custom fields.
URI
https://{InstanceURL}/api/travelprofile/v2.0/profile
Request parameters
All request parameters are optional. To identify a specific user by Login ID or XML Sync ID, you can specify the following request parameters:
| Parameter Name | Parameter Type | Data Type | Description |
|---|---|---|---|
userid_type |
Path |
string |
The type of user identification to use. Possible values are: login and xmlsyncid |
userid_value |
Path |
string |
The user's Login ID or XML Sync ID, depending on which user type is selected. This parameter must be provided in conjunction with the userid_type parameter. |
Headers
Content-Type header
application/xml
Authorization header
Authorization: OAuth {access_token}
Where access_token is the OAuth 2.0 access token of the user whose travel profile information you want to retrieve.
Create / Update Travel Profile
Creating/Updating a Profile uses the same model as what is retrieved.
Helpful Tips
- Minimum elements required to create a new user include:
FirstNameLastNameTravelConfigID(used to verify agency and Company access to create user)LoginIDPasswordRuleClass(uses default rule class if not provided)
- Omitted elements will be ignored and not updated
- Empty elements of datatype string will be cleared out; nillable elements will be cleared out if set as nil refer to XSD for nillable elements.
Headers
Content-Type header
application/xml
Authorization header
Authorization: OAuth {access_token}
Where access_token is the OAuth 2.0 access token of the user whose travel profile information you want to retrieve or update.
Schema
The complete schema definition is available here: Travel Profile XSD.
SAP Concur reserves the right to change the XSD. Reading/writing strictly to the XSD will result in breakage as new XML elements are added.
The Profile root element contains:
- General
- EmergencyContact
- Telephones
- Addresses
- NationalIDs
- DriversLicenses
- HasNoPassport
- Passports
- Visas
- EmailAddresses
- RatePreferences
- DiscountCodes
- Air
- Rail
- Car
- Hotel
- CustomFields
- Roles
- Sponsors
- TSAInfo
- UnusedTickets
- SouthwestUnusedTickets
- AdvantageMemberships
Travel Profile v2 - General
- Some elements require specific scopes be enabled to receive the data, refer to the table below.
- Profile fields, such as cost center and division, must be enabled and populated in the Travel site for data to return.
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
NamePrefix |
string |
The user's name prefix. Format: nvarchar(60) | - | - | - |
FirstName |
string |
The user's first name. Format: nvarchar(60) | - | Required | - |
MiddleName |
string |
The user's middle name. Format: nvarchar(60) | - | - | - |
LastName |
string |
The user's last name. Format: nvarchar(60) | - | Required | - |
NameSuffix |
string |
The user's name suffix. Format: nvarchar(60) | - | - | - |
PreferredName |
string |
The user's preferred name. Format: nvarchar(60) | - | - | - |
JobTitle |
string |
The user's job title. Format: nvarchar(255) | - | - | - |
CostCenter |
string |
The user’s cost center. Format: nvarchar(25) | - | - | Requires Company Details scope. |
CompanyEmployeeID |
string |
The user’s employee ID. Format: nvarchar(48) | - | - | Requires Company Details scope. Must be unique in the company. |
Division |
string |
The user's division. Format: nvarchar(60) | - | - | Requires Company Details scope. Must already be setup in the company configuration. |
PreferredLanguage |
string |
The user's preferred language locale. Example: United States English is en-US. Format: varchar(20) | - | - | - |
EReceiptOptIn |
boolean |
Whether the user has opted in to receive e-receipts. Format: true\false | - | - | |
HasOpenBooking |
boolean |
Whether the user has the TripLink User (formerly Open Booking User) permission. Format: true\false | Cannot Update | - | - |
CountryCode |
string |
The country code in from the ISO 3166-1 alpha-2 country code specification. Format: char(2) | Cannot Update | - | - |
CompanyName |
string |
The user's company name. Format: nvarchar(255) | Cannot Update | - | - |
CompanyID |
string |
The user's company ID. Format: varchar(255) | Cannot Update | - | Requires Company Details scope. |
RuleClass |
string |
The user's rule class. Format: nvarchar(60) | - | - | Must already be setup in the company. |
TravelConfigID |
string |
The user's TravelConfig. Format: varchar(255) | - | Required | - |
MedicalAlerts |
string |
The user's medical alerts. Format: nvarchar(255) | - | - | Requires Medical Alerts Scope. |
AgencyNumber |
string |
The TravelConfig’s Agency IATA Number. Format: varchar(255) | Cannot Update | - | - |
SearchID |
string |
The user's Search ID. Format: varchar(64) | - | - | - |
GDSProfileName |
string |
The user's GDS profile name. Format: varchar(60) | - | - | Requires TMC Specific scope. |
SabreProfileId |
string |
The user's Sabre Travel Profile Id. Format: varchar(60) | - | - | Requires TMC Specific scope. |
UUID |
string |
The user's Unique Identifier. Format: GUID, 32 characters | Cannot Update | - | Requires TMC Specific scope. |
NOTE: If MiddleName is provided, the NoMiddleName flag in TSAInfo section is set to false.
EmergencyContact
The emergency contact information provided.
- Emergency Contact Information scope must be enabled to receive the data.
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
Name |
string |
The emergency contact name Format: nvarchar(255) | - | - | - |
Relationship |
string |
The relationship to the user. Values are: Spouse, Brother, Parent, Sister, LifePartner, Other | - | - | - |
Phone |
list |
- | - | - | If multiple values of the same telephone type are provided, only the last one will be saved. See below for the list elements. |
Address |
Address |
Street Address. Format: nvarchar(max) | - | - | - |
Address
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
Street |
string |
Street Address. Format: nvarchar(max) | - | - | - |
City |
string |
The city name. Format: nvarchar(30) | - | - | - |
StateProvince |
string |
The state or province. Format: nvarchar(30) | - | - | - |
CountryCode |
string |
The country code in from the ISO 3166-1 alpha-2 country code specification. Format: char(2) | - | - | - |
PostalCode |
string |
The postal code. Format: nvarchar(20) | - | - | - |
Phone List
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
PhoneNumber |
string |
The emergency contact’s phone number. Format: nvarchar(60) | - | - | No unicode characters. |
Type |
string |
This contains a “type” attribute with values of DayTime or Alternate. | Required | Required | - |
Telephones
The Telephones parent element contains a Telephone child element for each included telephone. The Telephone element has the attributes shown in the Response Class section and contains the following child elements:
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
Type attribute |
string |
Type of phone. Values are: Home, Work, Fax, Pager, Other, and Cell | required | required | - |
ContactOptIn attribute |
boolean |
Whether the user has opted in to being contacted on this phone. Only appears when the phone type is Cell. Format: true\false | - | - | - |
PrimaryMobile attribute |
boolean |
This is the user's preferred mobile device. Format: true\false | - | - | - |
CountryCode |
string |
The country code in from the ISO 3166-1 alpha-2 country code specification. Format: Char(2) | required (Cell) | required (Cell) | Required for Cell types. |
PhoneNumber |
string |
The phone number as entered by the user, which may contain characters such as () or -. Format: nvarchar(60) |
required (Cell) | required (Cell) | Required for Cell types. |
Extension |
string |
The phone extension. Format: nvarchar(60) | - | - | - |
MobileDevice |
string |
The OS of the mobile device. Values are: Android Phone Android Tablet Blackberry iOS Phone iOS Tablet Not a smartphone Other iOS device Other smartphone Unknown Window Mobile |
- | - | - |
MobileName |
string |
The name the user assigned to the mobile device. Format: nvarchar(255) | - | - | - |
NOTES
- Telephone Types Other, Pager, Fax, Home, Work, Work2
- Ignores
CountryCode,DeviceName,DeviceType,ContactOptIn,IsPrimaryMobile - Only Work (NOT Work2) uses Extension
- Only a single number can be kept for each of these types. If more than one of each type is provided, W016 warning message is returned.
- Ignores
- Multiple cell phones can be updated, but will sync to the list provided. Cell phones missing from that list that currently associate with the user will be deleted.
PrimaryMobile:- If there is not exactly one (1)
PrimaryMobilespecified in changing cell phones, then all cell phone changes will be rejected. If only one (1) cell phone is provided, it is marked as primary.
- If there is not exactly one (1)
Addresses
The Addresses parent element contains an address child element for each included address. The address element has the attributes shown in the response class section and contains the following child elements:
NOTE: The values returned for the Address child elements are as entered by the user. The fields do not enforce formatting and may have a wide variety of values.
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
Type attribute |
string |
Address type. Values are: Home or Work | required | required | If multiple values are provided for either address type, the last one will be the one saved in the creation/update. |
Street |
string |
Street Address. Format: nvarchar(max) | - | - | - |
City |
string |
The city name. Format: nvarchar(30) | - | - | - |
StateProvince |
string |
The state or province. Format: nvarchar(30) | - | - | - |
CountryCode |
string |
The country code in from the ISO 3166-1 alpha-2 country code specification. Format: char(2) | - | - | - |
PostalCode |
string |
The postal code. Format: nvarchar(20) | - | - | - |
Longitude |
string |
Longitude value of Work Address. | Cannot Update | - | - |
Latitude |
string |
Latitude value of Work Address. | Cannot Update | - | - |
NationalIDs
The NationalIDs parent element contains a NationalID child element for each included National ID. The NationalID element contains the following child elements:
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
NationalIDNumber |
string |
The user's national identification number. Format: nvarchar(100) | - | - | No unicode accepted. Only saves one national ID value. If multiple are provided, W016 warning message is returned. |
IssuingCountry |
string |
The country the national ID was issued in. Format: varchar(2) | - | - | - |
Expiration |
date |
The expiration date of the national ID. Format: YYYY-MM-DD |
- | - | Min - 01/01/1753, Max - 12/31/9999 |
NOTE: Only one National ID can be accepted.
DriversLicenses
The DriversLicenses parent element contains a DriversLicense child element for each included licenses.
- The
DriversLicenseelement contains the following child elements:
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
DriversLicenseNumber |
string |
The user's driver license identification number. Format: nvarchar(100) | - | - | Only saves one Drivers License Number value. If multiple are provided, W016 warning message is returned. |
IssuingCountry |
string |
The country the license was issued in. Format: varchar(2) | - | - | - |
IssuingState |
string |
The state the license was issued in. Format: nvarchar(30) | - | - | - |
Expiration |
date |
The expiration date of the license. Format: YYYY-MM-DD |
- | - | Min - 01/01/1753, Max - 12/31/9999 |
NOTE: Only one Drivers License can be accepted.
HasNoPassport
A flag which is triggered automatically when adding a new passport to a user.
- Passport Visa Information scope must be enabled to receive or update the data.
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
HasNoPassport |
boolean |
Format: true\false. | - | If passport value added, then this value becomes false. |
Passports
A list of passports in the user's profile:
- Passport Visa Information scope must be enabled to receive the data.
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
PassportNumber |
string |
The user's passport number. Format: nvarchar(100) | Required | Required | - |
PassportNationality |
string |
The user's passport nationality. Format: char(2) | Required | Required | - |
PassportExpiration |
date |
The date the user’s passport expires. Format: YYYY-MM-DD |
- | - | Min - 01/01/1900, Max - 06/06/2079 |
PassportDateIssued |
date |
The date the user’s passport was issued. Format: YYYY-MM-DD |
- | - | Min - 01/01/1900, Max - 06/06/2079 |
PassportCityIssued |
string |
The city the user’s passport was issued in. Format: nvarchar(60) | - | - | - |
PassportCountryIssued |
string |
The country code in from the ISO 3166-1 alpha-2 country code specification. Format: char(2) | - | - | - |
NOTE: there can only be 2 passports associated to a user. If more than two passports are provided, W016 warning message is returned.
Visas
A list of visas in the user's profile.
- Passport Visa Information scope must be enabled to receive or update the data.
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
VisaNationality |
string |
The user's visa nationality. Format: char(2) | Required | Required | - |
VisaNumber |
string |
The user's visa nationality. Format: nvarchar(100) | Required | Required | - |
VisaType |
string |
The user's visa type. Values are Unknown, SingleEntry, DoubleEntry, MultiEntry, ESTA, ETA, and SchengenVisa. | - | - | - |
VisaDateIssued |
date |
The date the user’s visa was issued. Format: YYYY-MM-DD |
- | - | Min - 01/01/1900 Max - 06/06/2079 |
VisaExpiration |
date |
The date the user’s visa expires. Format: YYYY-MM-DD |
- | - | Min -01/01/1900 Max - 06/06/2079 |
VisaCityIssued |
string |
The city the user’s visa was issued in. Format: nvarchar(60) | - | - | - |
VisaCountryIssued |
string |
The country code in from the ISO 3166-1 alpha-2 country code specification. Format: char(2) | - | - | - |
NOTE: Visas will sync with existing visas. Any existing Visas not provided in the list will be deleted.
EmailAddresses
The EmailAddresses parent element contains an EmailAddress child element for each included email address. It contains the following child element:
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
EmailAddress |
string |
The user's email address. Format: Varchar(255) | - | - | - |
Contact attribute |
boolean |
The Contact attribute specifies whether the email address should be used for travel notifications. Format: true\false. | - | - | - |
Type attribute |
string |
The type of email address. Values are: Business, Personal, Supervisor, TravelArranger, Business2, Other1, and Other2. | Required | Required | Supervisor and TravelArranger cannot be updated. Only 1 of each type is allowed. W016 Error is returned |
RatePreferences
The RatePreferences parent element contains the following child element:
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
AAARate |
boolean |
Whether the user is eligible for the AAA rate. Format: true\false | - | - | - |
AARPRate |
boolean |
Whether the user is eligible for the AARP rate. Format: true\false | - | - | - |
GovtRate |
boolean |
Whether the user is eligible for the Government rate. Format: true\false | - | - | - |
MilitaryRate |
boolean |
Whether the user is eligible for the Military rate. Format: true\false | - | - | - |
DiscountCodes
The DiscountCodes parent element contains a DiscountCode child element for each included discount code.
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
DiscountCode |
string |
The discount code for the specified vendor. | - | - | unable to update |
Vendor attribute |
string |
Specifies the name of the vendor for the discount code. | - | - | unable to update |
NOTE: Discount code elements are not available to create or update.
Air
The Air parent element contains the user's air travel preferences and contains the following child elements:
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
AirMemberships |
- | The AirMemberships element only appears if the request came from a travel supplier for this travel type, or from a TMC. This element contains AirMembership child elements. | - | - | - |
Seat |
- | This element contains air seat child elements. | - | - | - |
Meals |
string |
This parent element contains the MealCode child element that indicates the meal preference of the traveler. See Reference for possible values. | - | - | Defaults to Regular Meal |
HomeAirport |
string |
The user's home airport. varchar(3) | - | - | Must be an existing IATA code. |
AirOther |
string |
Other Air related description | - | - | - |
Air Memberships
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
VendorCode |
string |
The code for the vendor that manages the loyalty program. varchar(2) | Required | Required | Must be a valid VendorCode for the membership type. This list can be made available upon request. |
AccountNo |
string |
The user's account identifier in the loyalty program. varchar(60) | Required | Required | - |
Status |
string |
Name of the user's current level in the loyalty program. varchar (100) | - | - | - |
StatusBenefits |
string |
Description of a benefit of the loyalty program at the current status. | - | - | - |
PointTotal |
string |
The user's total number of points in the loyalty program. | - | - | - |
SegmentTotal |
string |
The user's total segments in the loyalty program. | - | - | - |
NextStatus |
string |
Name or description of next higher status level in the loyalty program. | - | - | - |
PointsUntilNextStatus |
string |
Loyalty points required to next status level. | - | - | - |
SegmentsUntilNextStatus |
string |
Booking segments to next status level. | - | - | - |
IsSenator |
boolean |
Lufthansa specific field. Format: true\false | - | - | - |
Seat
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
InterRowPositionCode |
string |
Preferred position in an airplane row. Format: Window, Aisle, Middle, DontCare. |
- | - | - |
SectionPositionCode |
string |
Preference for position in plane. Format: Bulkhead, Forward, Rear, ExitRow, DontCare. |
- | - | - |
Rail
The Rail parent element contains the user's rail travel preferences and contains the following child elements:
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
Seat |
string |
This element contains seat preferences. Format: Aisle, Window, DontCare |
- | - | - |
Coach |
string |
This element contains coach preferences. Format: Compartment, Coach, CoachWithTable, DontCare |
- | - | - |
NoiseComfort |
string |
This element contains noise comfort preferences. Format: QuietSpace, MobileSpace, DontCare |
- | - | - |
Bed |
string |
This element contains bed preferences. Format: Lower, Upper, Middle, DontCare |
- | - | - |
BedCategory |
string |
This element contains bed category preferences. Format: WomenOnly, MenOnly, DontCare |
- | - | - |
Berth |
string |
This element contains berth preferences. Format: Lower, Upper, Middle, DontCare |
- | - | - |
Deck |
string |
This element contains deck preferences. Format: Lower, Upper, DontCare |
- | - | - |
SpaceType |
string |
This element contains space type preferences. Format: Panorama, SeatWithTable, Solo, Salon, Kiosk, InclineSeat, DuoSideBySide, DuoFaceToFace, Club6, Club4, Carre, DisabledCompanionSpace, DontCare |
- | - | - |
FareSpaceComfort |
string |
This element contains fare space comfort preferences. Format: DedicatedBusiness, Business, IntermediateLeisure, Leisure, StandardLeisure, DontCare |
- | - | - |
SpecialMeals |
string |
This element contains special meal preferences. Format: LowFat, LowSalt, GlutenFree, Diabetic, Muslim, Kosher, Vegetarian, VegetarianLactoOvo, DontCare |
- | - | - |
Contingencies |
string |
This element contains contingencies preferences. Format: Bike, WomenOnly, WheelchairSpace, DontCare |
- | - | - |
RailMemberships |
- | This element contains RailMembership child elements | - | - | - |
Rail Membership
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
VendorCode |
string |
The code for the vendor that manages the loyalty program. varchar(2) | Required | Required | Must be a Valid Vendor Code for the Membership Type. This list can be made available upon request. |
AccountNo |
string |
The user's account identifier in the loyalty program. varchar(60) | Required | Required | See Below. |
Status |
string |
Name of the user's current level in the loyalty program. varchar (100) | - | - | - |
StatusBenefits |
string |
Description of a benefit of the loyalty program at the current status. | - | - | - |
PointTotal |
string |
The user's total number of points in the loyalty program. | - | - | - |
SegmentTotal |
string |
The user's total segments in the loyalty program. | - | - | - |
Expiration |
DateTime |
The user's expiration date in the loyalty program. Min - 01/01/1753, Max - 12/31/9999 | - | - | - |
NextStatus |
string |
Name or description of next higher status level in the loyalty program. | - | - | - |
PointsUntilNextStatus |
string |
Loyalty points required to next status level. | - | - | - |
SegmentsUntilNextStatus |
string |
Booking segments to next status level. | - | - | - |
BahnCardClass |
string |
Bahn card class. Valid values are First and Second. | - | - | - |
BahnCardType |
string |
Bahn card type. Valid values include NA (for non-rail programs), Card25, Card50, Card100, Business25, and Business50. | - | - | - |
Car
The Car parent element contains the user's car travel preferences. It contains the following child elements:
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
CarSmokingCode |
string |
Smoking car preferred. Format: DontCare, NonSmoking, Smoking |
- | - | - |
CarGPS |
boolean |
Car GPS preference. Format: true\false. | - | - | - |
CarType |
string |
Car type preference. Values are: DontCare Mini Economy EconomyHybrid Compact CompactHybrid Intermediate IntermediateHybrid Standard StandardHybrid FullSize FullSizeHybrid MiniVan Luxury Premium StandardSUV IntermediateSUV FullSizeSUV FullSizePickup Specialized |
- | - | - |
CarMemberships |
- | The CarMemberships element only appears if the request came from a travel supplier for this travel type, or from a TMC. This element contains CarMembership child elements for each included membership. | - | - | - |
CarOther |
string |
Other Car related description. Format: varchar(30) | - | - | - |
CarSkiRack |
boolean |
Car ski rack preference. Format: true\false. | - | - | |
CarTransmission |
string |
Car transmission type. Values are: DontCare, Automatic, Manual |
- | - | - |
Car Memberships
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
VendorCode |
string |
The code for the vendor that manages the loyalty program. varchar(2) | Required | Required | Must be a Valid Vendor Code for the Membership Type. This list can be made available upon request. |
AccountNo |
string |
The user's account identifier in the loyalty program. varchar(60) | Required | Required | See Below. |
Status |
string |
Name of the user's current level in the loyalty program. varchar (100) | - | - | - |
StatusBenefits |
string |
Description of a benefit of the loyalty program at the current status. | - | - | - |
PointTotal |
string |
The user's total number of points in the loyalty program. | - | - | - |
SegmentTotal |
string |
The user's total segments in the loyalty program. | - | - | - |
Expiration |
DateTime |
The user's expiration date in the loyalty program. | - | - | Min - 01/01/1753, Max - 12/31/9999 |
NextStatus |
string |
Name or description of next higher status level in the loyalty program. | - | - | - |
PointsUntilNextStatus |
string |
Loyalty points required to next status level. | - | - | - |
SegmentsUntilNextStatus |
string |
Booking segments to next status level. | - | - | - |
Hotel
The Hotel parent element contains the user's hotel travel preferences. It contains the following child elements:
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
SmokingCode |
string |
Smoking room preference. Values: DontCare, NonSmoking,Smoking |
- | - | - |
HotelMemberships |
- | This parent element only appears if the request came from a travel supplier for this travel type, or from a TMC. This element contains HotelMembership child elements for each included membership. | - | - | - |
RoomType |
string |
Hotel room preference. Values are: DontCare, King, Queen, Double, Twin, Single, Disability |
- | - | - |
HotelOther |
string |
Other Hotel related description. Format: varchar(30) | - | - | - |
PreferFoamPillows |
boolean |
Whether the user prefers foam pillows. Format: true\false. | - | - | - |
PreferCrib |
boolean |
Whether the user prefers to have a crib. Format:true\false. | - | - | - |
PreferRollawayBed |
boolean |
Whether the user prefers to have a rollaway bed. Format:true\false. | - | - | - |
PreferGym |
boolean |
Whether the user prefers a hotel with a gym. Format:true\false. | - | - | - |
PreferPool |
boolean |
Whether the user prefers a hotel with a pool. Format:true\false. | - | - | - |
PreferRestaraunt |
boolean |
Whether the user prefers a hotel with a restaurant. Format:true\false. | - | - | - |
PreferWheelchairAccess |
boolean |
Whether the user requires wheelchair access. Format: true\false. | - | - | - |
PreferAccessForBlind |
boolean |
Whether the user requires a room with access for blind guests. Format:true\false. | - | - | - |
PreferRoomService |
boolean |
Whether the user prefers a hotel with room service. Format:true\false. | - | - | - |
PreferEarlyCheckIn |
boolean |
Whether the user prefers a hotel with early check in. Format:true\false. | - | - | - |
Hotel Memberships
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
VendorCode |
string |
The code for the vendor that manages the loyalty program. varchar(2) | Required | Required | Must be a Valid Vendor Code for the Membership Type. This list can be made available upon request. |
AccountNo |
string |
The user's account identifier in the loyalty program. varchar(60) | Required | Required | See Below. |
Status |
string |
Name of the user's current level in the loyalty program. varchar (100) | - | - | - |
StatusBenefits |
string |
Description of a benefit of the loyalty program at the current status. | - | - | - |
PointTotal |
string |
The user's total number of points in the loyalty program. | - | - | - |
SegmentTotal |
string |
The user's total segments in the loyalty program. | - | - | - |
Expiration |
DateTime |
The user's expiration date in the loyalty program. | - | - | Min - 01/01/1753, Max - 12/31/9999 |
CustomFields
The CustomFields parent element contains a CustomField child element for each field.
- Company Details scope must be enabled to receive the data.
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
CustomField |
string |
The value of the custom field. Format: varchar(255) | - | - | - |
Name attribute |
string |
The name of the custom field. Format: varchar(255) | Required | Required | - |
Roles
A list of users associated to a user:
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
FirstName |
string |
The Arranger/Manager's first name. Format: varchar(60) | Cannot Update | - | - |
LastName |
string |
The Arranger/Manager's last name. Format: varchar(60) | Cannot Update | - | - |
EmailAddress |
string |
The Arranger/Manager's email address. Format: varchar(255) | Cannot Update | - | - |
LoginId |
string |
The Login Id for Arranger/Manager | Required | Required | - |
Type attribute |
string |
The Arranger/Manager's role. Values are: Arranger, Manager | Required | Required | - |
PrimaryIndicatorFlag attribute |
boolean |
For Arrangers type, denotes the primary arranger. Format: true\false. | - | - | - |
NOTES:
FirstName,LastName, andEmailcannot be updated.ManagersandArrangersmust be in the same company of the user to be assigned.- If the
PrimaryIndicatorFlagis sent in as true, the arranger will be marked as primary. - New arrangers will be marked as travel arrangers only.
- If multiple primary arrangers are provided, W016 warning message is returned.
- If multiple managers are provided, W016 warning message is returned.
Sponsors
A list of sponsors associated to a user:
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
NonEmployeeUserType |
string |
The non-employee's user type. Values are: Contractor, Student/Intern, Candidate for Hire, Invitational Traveler, Dependent/Spouse, Board Member, Other |
Required | Required | - |
SponsorName |
string |
The sponsor’s name. Format: varchar(255) | Cannot Update | - | - |
SponsorshipStartDate |
date |
The sponsorship start date. Format: YYYY-MM-DD |
Required | Required | - |
SponsorshipEndDate |
date |
The sponsorship end date. Format: YYYY-MM-DD |
Required | Required | - |
LoginID |
string |
The sponsor’s name. Format: varchar(255) | Required | Required | - |
NOTES:
- The company must allow sponsored users, and the sponsoring user must have the “Sponsor” role to be added to the list of sponsors
- The sponsoring user must be associated with the same company as the sponsored user.
- If the association to the sponsoring user already exists, than the data will be updated
SponsorshipEndDatemust be afterSponsorshipStartDate
TSAInfo
The Transportation Security Administration (TSA) details provided.
- TSA information scope must be enabled to receive the data.
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
Gender |
string |
The user's gender. Values are: Male, Female |
- | - | - |
DateOfBirth |
date |
The user’s date of birth. Format: YYYY-MM-DD. Min - 01/01/1900, Max - 06/06/2079 |
- | - | - |
NoMiddleName |
boolean |
Format: true/false |
- | - | - |
PreCheckNumber |
string |
The user’s pre-check number. Format: varchar(255) | - | - | - |
RedressNumber |
string |
The user’s redress number. Format: varchar(255) | - | - | - |
NOTE: NoMiddleName: If the profile has a middle name, NoMiddleName overrides to false
UnusedTickets
A list of unused tickets associated to a user
- Unused tickets scope must be enabled to receive the data.
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
Carrier |
string |
The vendor’s name. Format: Varchar(255) | Required | Required | - |
TicketNumber |
string |
The unused ticket number. Format: Varchar(255) | Required | Required | - |
RecordLocator |
string |
The unused ticket record locator. Format: Varchar(6) | - | - | - |
BaseFare |
string |
The base fare of the unused ticket. Format: Varchar(255) | - | - | - |
Taxes |
string |
The taxes for the unused ticket. Format: Varchar(255) | - | - | - |
Fees |
string |
The fees for the unused ticket. Format: Varchar(255) | - | - | - |
Currency |
string |
The currency of the unused ticket. Format: Varchar(3) | - | - | - |
TicketType |
string |
The type of unused ticket. Format: Varchar(1) | - | - | - |
IssueDate |
date |
The date of issue for the unused ticket. Format: YYYY-MM-DD. |
- | - | Min - 01/01/1753, Max - 12/31/9999 |
ExpirationDate |
date |
The date of expiration for the unused ticket. Format: YYYY-MM-DD. |
- | - | Min - 01/01/1753, Max - 12/31/9999 |
Notes |
string |
Notes associated to the unused ticket. Format: Varchar(255) | - | - | - |
SouthwestUnusedTickets
A list of unused Southwest tickets associated to a user.
- Unused tickets scope must be enabled to receive the data.
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
RecordLocator |
string |
The unused ticket record locator. Format: Varchar(255) | Required | - | - |
TicketAmount |
string |
The amount of the unused ticket. Format: Varchar(255) | - | - | - |
Currency |
string |
The currency of the unused ticket. Format: Varchar(3) | - | - | - |
ExpirationDate |
date |
The date of expiration for the unused ticket. Format: YYYY-MM-DD. |
- | - | Min - 01/01/1753, Max - 12/31/9999 |
AdvantageMemberships
A list of advantage memberships associated to a user:
| Name | Data Type | Description | Update | Create | Comments |
|---|---|---|---|---|---|
VendorCode |
string |
The code for the vendor that manages the membership program. Format: Varchar(2) | Required | Required | - |
VendorType |
string |
The vendor type. Values are: Air, Rail, Car, Hotel |
Required | Required | - |
ProgramNumber |
string |
The membership program number. Format: Varchar(20) | Required | Required | - |
OriginCode |
string |
The origin code. Format: Varchar(12) | - | - | - |
DestinationCode |
string |
The destination code. Format: Varchar(12) | - | - | - |
ProgramCode |
string |
The program code. Format: Varchar(20) | Required | Required | - |
ExpirationDate |
date |
Expiration date. Format: YYYY-MM-DD. Min - 01/01/1900, Max - 06/06/2079 |
- | - | - |
OptionCode |
string |
The option code. Format: Varchar(20) | - | - | - |
ProgramName |
string |
The program name. Format: Varchar(20) | Cannot Update | - | - |
NOTES:
- For List of available advantage memberships See Reference
- Multiple memberships for the same
VendorType,VendorCode,ProgramCode, andCardNumberare identified and a warning is thrown. OriginStationCodeandDestinationStationCodefields are deprecated and should no longer be used. UseOriginCodeandDestinationCodeinstead.
Possible Warnings and Error Messages
Error in XML Document
This error message occurs, when the XML is not formatted in such a way that it can be read.
<Error>
<Message>There is an error in XML document (1, 147).</Message>
<Server-Time>2017-06-22T16:51:37</Server-Time>
<Id>3BDBC49E-8793-4515-BA0E-F9C71ADA7330</Id>
</Error>
The best way to find the cause of the error is by taking the body of your message and comparing it against the Travel Profile XSD. You can use free online sites to validate such as https://www.freeformatter.com/xml-validator-xsd.html
Standard Error Codes
The codes and types of messages that can be returned on updates and creates:
| CODE | Message Type | Notes | Example |
|---|---|---|---|
| S001 | Success | Process completed successfully. | Success, no errors or warnings reported. |
| E001 | No Access | No access to user data. | - |
| E002 | Required Field Missing | The field noted is required for updates or creates, no changes were made. | - |
| W001 | Invalid Regex | The given data does not match the expected regex. | - |
| W002 | Invalid Length | The given data is too long or too short. | - |
| W003 | Not Found In Company | The given user was not found in the company. | - |
| W004 | Duplicate Entry | The given data is duplicated and not allowed. | - |
| W005 | Duplicate LoginId | The given LoginID is duplicated. |
- |
| W006 | Out of Range | The given data is out of range. | - |
| W007 | Field is Required | The given field cannot be cleared. | - |
| W009 | Invalid Account Number | Account number check failed due to length, Luhn, etc. | - |
| W010 | Invalid Vendor Code | Vendor code given is invalid. | - |
| W011 | Cannot Change | The given field cannot be altered. | - |
| W012 | Primary Cell Number Error | Data violates one primary cell phone requirement. | - |
| W013 | Invalid Custom Field | The data provided is invalid for the custom field. | - |
| W014 | Invalid Date Range | The data provided is outside of acceptable date range. | - |
| W015 | Invalid GUID | The GUID is invalid. | - |
| W016 | Too Many Items | There are too many items in the given list. | - |
| W017 | No Access to VendorCode | The user lacks access to the given vendor code. | - |
If incorrect API credentials are provided, the service will return the standard response, e.g. 403 Forbidden. In some cases, the API will return additional information when producing a 400, Bad Request, response. It may contain the following codes in the response's body: * EC1 : The user was not found in database. * EC2: The user is not a company admin, or the company ID does not match the user's company ID. * EC3: The user is not an agency admin, the agency company ID is null, or if agency company ID does not match the user's agency company ID. * EC4: If the application's UUID is null, or if the application is configured not to have access to the input travel config.
Examples for Travel Suppliers
Example 1: Get the travel profile for the user associated with the specified OAuth 2.0 access token
Request
GET {InstanceURI}/api/travelprofile/v2.0/profile HTTP/1.1
Authorization: OAuth {access token}
Example 2: Get the travel profile for a user with a specific login ID
Request
GET https://www.concursolutions.com/api/travelprofile/v2.0/profile?userid_type=login&userid_value=cm@example.com HTTP/1.1
Authorization: OAuth {access token}
Examples for TMCs
Example 3: Get the travel profile for the user associated with the specified OAuth 2.0 access token
Request
GET {InstanceURI}/api/travelprofile/v2.0/profile HTTP/1.1
Authorization: OAuth {access token}
Example 4: Get the travel profile for a user with a specific login ID
Request
GET https://www.concursolutions.com/api/travelprofile/v2.0/profile?userid_type=login&userid_value=cm@example.com HTTP/1.1
Authorization: OAuth {access token}
Example 5: Create a new user
Request
POST https://www.concursolutions.com/api/travelprofile/v2.0/profile HTTP/1.1
Authorization: OAuth {access token}
Body
<ProfileResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Action="Create" LoginId="william.never@email.com">
<General>
<FirstName>William</FirstName>
<LastName>Never</LastName>
<RuleClass>Default Rule Class</RuleClass>
<TravelConfigID>555</TravelConfigID>
</General>
<Password>password123</Password>
</ProfileResponse>
Example 6: Update a user
Request
POST https://www.concursolutions.com/api/travelprofile/v2.0/profile HTTP/1.1
Authorization: OAuth {access token}
Body
<ProfileResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Action="Update" LoginId="william.never@email.com">
<General>
<FirstName>Bill</FirstName>
</General>
</ProfileResponse>
Get a list of travel profile summaries
This endpoint provides a list of travel profile summaries that have been updated since the specified date. The response is separated into pages.
Request
GET {InstanceURI}/api/travelprofile/v2.0/summary?LastModifiedDate=2015-01-01T01:00:00 HTTP/1.1
Authorization: OAuth {access token}
Request parameters
All request parameters are optional. Available request parameters are as follows:
| Parameter Name | Required/Optional | Parameter Type | Data Type | Description |
|---|---|---|---|---|
LastModifiedDate |
Required | path | string |
The date and time, in UTC, that the profiles must be updated after to be included in the response. Format: YYYY-MM-DDThh:mm:ss |
Page |
Optional | path | string |
The number of pages to retrieve. If the page is outside the number of existing pages, the response elements will be empty |
ItemsPerPage |
Optional | path | string |
The number of travel profiles per page. The maximum value is 200. The default value is 200. |
Headers
Accept header
application/xml
Authorization header
Authorization: OAuth {access_token}
Where access_token is the OAuth 2.0 access token of the user whose travel profile summaries you want to retrieve. If you want to access company-wide travel profile information, the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.
Schema
The data model of the response for the GET operation. The complete schema definition is also available here: Travel Profile Summary V2 XSD
<ConnectResponse>
<Metadata>
<Paging>
<TotalPages />
<TotalItems />
<Page />
<ItemsPerPage />
<PreviousPageURL />
<NextPageURL />
</Paging>
</Metadata>
<Data>
<ProfileSummary>
<Status />
<LoginID />
<XmlProfileSyncID />
<ProfileLastModifiedUTC />
</ProfileSummary>
</Data>
</ConnectResponse>
Response
ConnectResponse root element
The ConnectResponse root element contains the General, Telephones, Addresses, DriversLicenses, EmailAddresses, RatePreferences, DiscountCodes, Air, Car, Hotel, and CustomFields child elements. It has the attributes shown in the response class section.
Metadata element
The Metadata parent element contains the Paging child element.
Paging elements
The Paging parent element contains contains the paging information for the response and it contains the following child elements:
| Element Name | Data Type | Description |
|---|---|---|
| TotalPages | string |
The total number of pages to return. |
| TotalItems | string |
The total number of profiles the query returned. |
| Page | string |
The page number for the set of results in the current response. |
| ItemsPerPage | string |
The number of items set to display per page. |
| PreviousPageURL | string |
The URI to the previous page of results. This element will be empty when there are no previous pages. |
| NextPageURL | string |
The URI to the next set of results. This element will be empty when there are no next pages |
Data element
The Data parent element contains a ProfileSummary child element for each included travel profile.
ProfileSummary
The ProfileSummary element contains the profile information for the response and it contains the following child elements:
| Element Name | Data Type | Description |
|---|---|---|
| Status | string |
Current status of the user: Active or Inactive. |
| LoginID | string |
The SAP Concur user login ID. |
| XMLProfileSyncID | string |
The user's XML Profile Sync ID, if available. |
| ProfileLastModifiedUTC | string |
The date, in UTC, when the travel profile was last modified. Format: YYYY-MM-DDThh:mm:ss. |
Example
This example gets the list of travel profile summaries modified after January 1 2015.
Request
GET {InstanceURI}/api/travelprofile/v2.0/summary?LastModifiedDate=2015-01-01T01:00:00 HTTP/1.1
Authorization: OAuth {access token}
Response
HTTP/1.1 200 OK
Content-Type: application/xml
<ConnectResponse>
<Metadata>
<Paging>
<TotalPages>1</TotalPages>
<TotalItems>2</TotalItems>
<Page>1</Page>
<ItemsPerPage>200</ItemsPerPage>
<PreviousPageURL />
<NextPageURL />
</Paging>
</Metadata>
<Data>
<ProfileSummary>
<Status>Active</Status>
<LoginID>mariab@company1.com</LoginID>
<XmlProfileSyncID>`string`123</XmlProfileSyncID>
<ProfileLastModifiedUTC>2015-01-01T01:00:00</ProfileLastModifiedUTC>
</ProfileSummary>
<ProfileSummary>
<Status>Inactive</Status>
<LoginID>peterk@company1.com</LoginID>
<XmlProfileSyncID>`string`456</XmlProfileSyncID>
<ProfileLastModifiedUTC>2015-01-01T01:00:00</ProfileLastModifiedUTC>
</ProfileSummary>
</Data>
</ConnectResponse>
Travel Profile v1 - Loyalty Program
The loyalty program information for the user, as entered in SAP Concur.
URI
https://www.concursolutions.com/api/travelprofile/v1.0/loyalty
Content Types
- application/xml
Accept Types
- application/xml
Operations
Update Loyalty Program Information
Updates the loyalty program information for the OAuth consumer. Loyalty contains a variety of information about the user's loyalty membership, including:
- Vendor
- Number
- Status
- Points Total
- Segment Total
- Next Status
- Points to Next Status
- Segments to Next Status
Travel Suppliers
If the request is sent from a travel supplier with an Pre-2017 Authorization (Deprecated) token for the user, they can set a new loyalty program number. Travel suppliers can only update their own loyalty program information.
Travel Management Companies
If the request is sent by a TMC, the request can update any loyalty program for the OAuth consumer.
Restrictions
This function is only available to travel suppliers who have completed the SAP Concur application review process. Suppliers may post loyalty membership information for their loyalty programs only.
Request
Headers
Authorization Header
Authorization header with OAuth token for valid SAP Concur user. Required.
Accept Header
application/xml
Request Body
This request contains the LoyaltyMembershipUpdate parent element with a Membership child element for each included loyalty program. The Membership element has a UniqueID attribute containing the loyalty program identifier, and the following child elements.
Update Loyalty Program Membership Request Schema
| Element | Description |
|---|---|
VendorCode |
The code for the vendor that manages the loyalty program. This element is required when the request is sent by a TMC, and is ignored when the request is sent by a travel supplier. |
VendorType |
The type of vendor that manages the loyalty program. Format: A, C or H A – Air C – Car H – Hotel This element is required when the request is sent by a TMC, and is ignored when the request is sent by a travel supplier. |
AccountNo |
The user's account identifier in the loyalty program. |
Status |
Name of the user's current level in the loyalty program. Examples: Gold or Premier. |
StatusBenefits |
Description of a benefit of the loyalty program at the current status. Example: You are entitled to free breakfast. |
PointTotal |
The user's total number of points in the loyalty program. |
SegmentTotal |
The user's total segments in the loyalty program. |
NextStatus |
Name or description of next higher status level in the loyalty program. |
PointsUntilNextStatus |
Loyalty points required to next status level. |
SegmentsUntilNextStatus |
Booking segments to next status level. |
XML Example Request From Travel Supplier
POST https://www.concursolutions.com/api/travelprofile/v1.0/loyalty HTTP/1.1
Authorization: OAuth {access token}
<LoyaltyMembershipUpdate>
<Membership UniqueID="Frequent Flier">
<AccountNo>1234567890</AccountNo>
<Status>Gold</Status>
<StatusBenefits>Early flight check-in.</StatusBenefits>
<PointTotal>123456</PointTotal>
<SegmentTotal>150</SegmentTotal>
<NextStatus>Platinum</NextStatus>
<PointsUntilNextStatus>100000</PointsUntilNextStatus>
<SegmentsUntilNextStatus>100</SegmentsUntilNextStatus>
</Membership>
<Membership UniqueID="Business Traveler">
<AccountNo>0987654321</AccountNo>
<Status>Preferred</Status>
<StatusBenefits>Free upgrade to Business Class where available.</StatusBenefits>
<PointTotal>334002</PointTotal>
<SegmentTotal>340</SegmentTotal>
<NextStatus>Premier</NextStatus>
<PointsUntilNextStatus>200998</PointsUntilNextStatus>
<SegmentsUntilNextStatus>110</SegmentsUntilNextStatus>
</Membership>
</LoyaltyMembershipUpdate>
XML Example Request From TMC
POST https://www.concursolutions.com/api/travelprofile/v1.0/loyalty HTTP/1.1
Authorization: OAuth {access token}
<LoyaltyMembershipUpdate>
<Membership UniqueID="Frequent Flier">
<VendorCode>AA</VendorCode>
<VendorType>A</VendorType>
<AccountNo>1234567890</AccountNo>
<Status>Gold</Status>
<StatusBenefits>Early flight check-in.</StatusBenefits>
<PointTotal>123456</PointTotal>
<SegmentTotal>150</SegmentTotal>
<NextStatus>Platinum</NextStatus>
<PointsUntilNextStatus>100000</PointsUntilNextStatus>
<SegmentsUntilNextStatus>100</SegmentsUntilNextStatus>
</Membership>
<Membership UniqueID="Business Traveler">
<VendorCode>TR</VendorCode>
<VendorType>C</VendorType>
<AccountNo>991823728</AccountNo>
<Status>Preferred</Status>
<StatusBenefits>Free upgrade to larger car when available.</StatusBenefits>
<PointTotal>822311</PointTotal>
<SegmentTotal>340</SegmentTotal>
<NextStatus>Premier</NextStatus>
<PointsUntilNextStatus>200998</PointsUntilNextStatus>
<SegmentsUntilNextStatus>110</SegmentsUntilNextStatus>
</Membership>
</LoyaltyMembershipUpdate>
Response
Content Types
application/xml
Update Loyalty Program Membership Response Schema
This request will return a LoyaltyMembershipResponse parent element with the following child elements:
| Element | Description |
|---|---|
Status |
The status of the update request. Format: OK or ERROR |
ErrorDescription |
The details of the error. Only contains data if the Status is ERROR. |
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
<LoyaltyMembershipResponse>
<Status>OK</Status>
<ErrorDescription />
</LoyaltyMembershipResponse>
Travel
Travel Services
Overview
The Travel services consists of a set of APIs that provide programmatic access to travel data such as itineraries, travel profiles, travel requests, and travel loyalty program information. These APIs are categorized into three sets of web services:
Itinerary
The Concur Itinerary web service can be used to pro grammatically access travel data such as trips and bookings in the Concur travel system. The Concur Travel system uses this data to match and consolidate bookings it receives from disparate sources and put these into consolidated travelers’ itineraries, providing travelers a convenient way to view their trips in a single itinerary view. Travelers can view their itineraries through mobile applications or other services.
Travel Profile Web Service
The Travel Profile Web Service consists of a set of resources that provide travel profile functionality customized in specific ways for developers, travel suppliers, and travel management companies (TMCs). Depending on who is using this web service, it provides the ability to update travel loyalty information, and subscribe and unsubscribe to travel profile changes.
Travel requests
Concur Travel Request web service is designed to help businesses control expenses by requiring employees to obtain approval before incurring expenses. It provides the ability to view requests and update the workflow for travel requests.
Trip approval
The Trip Approval resource allows clients to approve or reject trips. Clients send the unique identifier for the trip, the approver email and the workflow action to be performed (either approve or reject).
Itinerary API - Overview & Getting Started
Itinerary Service
- Overview
- Version
- Resources
- Concepts
- Who Can Use This Web Service?
- Authentication and Authorization
- Configuration
- FAQs
- Best Practices
- Reference
Overview
The Itinerary API can be used to programmatically access travel data such as trips and bookings in Concur Travel. Concur Travel uses this data to match and consolidate bookings it receives from disparate sources and put these into consolidated travelers’ itineraries, providing travelers a convenient way to view their trips in a single itinerary view. Travelers can view their itineraries through mobile applications or other services.
Version
Version 1.0
Resources
Concepts
Itineraries and Trips
The terms itinerary and trip are synonyms. Trip is the name used for the SAP Concur web service resource that represents an itinerary.
Itinerary, Booking Record, and Segment
- An itinerary is the container for all bookings in a trip. An itinerary can have more than one booking.
- A booking record is the container for all segments booked from a source with the same unique identifier (record locator or confirmation number). A single booking can have multiple segments.
- A segment includes details about the travel booking.
Who Can Use This Web Service?
TripLink suppliers, travel management companies (TMCs), and SAP Concur clients and third-party developers can use the Itinerary API. The level of access to the data in the Concur Travel system depends on who is accessing it and the SAP Concur products that have been purchased.
Travel Management Companies
- Can view and post bookings for any travel type.
- Send new reservations that users create on the supplier's site to SAP Concur.
- Send a notice of trip cancellations to SAP Concur.
- Get a list of current trips for a user from SAP Concur.
- Get the full details of user trips from SAP Concur.
- Can view the full set of fields for their customers' itineraries because TMCs have an existing relationship with their customers.
- Can send proposed itineraries when the Agency Proposal feature of Concur Request is active.
- Can cancel bookings on behalf of a user.
TripLink Travel Suppliers
- Can post bookings for their travel type.
- Get limited itinerary details.
- Get the full details of the bookings that they own, but see a limited set of fields and data for other bookings.
- Modify bookings.
- Cancel bookings for their travel type.
SAP Concur Clients and Third-Party Developers
- Get trip information for SAP Concur users. SAP Concur clients who purchase Web Services have access to their own trip data, while third party developers have access to the SAP Concur trip data of the clients who authorize them.
- Third-party partner developers must determine which configurations are required for their solution prior to the review process.
If you would like to start using this web service, please visit: http://www.concur.com/en-us/connect-platform/suppliers or contact the SAP Partner Enablement Team. SAP Concur products are highly configurable, and not all clients will have access to all features.
Some itinerary data may have come from Sabre. SAP Concur encourages you to speak to Sabre about becoming a Sabre Authorized Developer.
Authentication and Authorization
The Itinerary API uses OAuth 2.0 for authenticating users and authorizing access to travel data.
Authorization for TMCs
TMCs can request or send travel bookings in two ways:
- By using an OAuth token for the user the travel booking belongs to. This token allows access to the user's data.
- By using an OAuth token for a user with an administrative role at the company, which allows access to company-wide information. The user who authenticates during this OAuth process must have an SAP Concur account with one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
Authorization for TripLink Suppliers
The travel supplier can request or send travel bookings by using an OAuth token for the user the travel booking belongs to, generated with the user's involvement.
Configuration
- If you are a TMC, third-party developer, or a TripLink supplier who would like to start using this web service, please visit: http://www.concur.com/en-us/connect-platform/suppliers or contact the SAP Partner Enablement Team.
- SAP Concur products are highly configurable, and not all SAP Concur clients will have access to all features.
- Partner developers must determine which configurations are required for their solution prior to the review process.
FAQs
When Do I Send Trips Versus Bookings?
- TMCs, OTA, or partners that own or manage the entire trip on behalf of the traveler should send trips.
- Travel suppliers such as hotels, car vendors or airlines that own only parts of the trips should send bookings.
- Posted bookings are merged with any existing trips if their dates overlap.
- Posted trips are not merged even if a trip already exists with overlapping dates.
Can Other TripLink Suppliers See all the Booking Details of My Bookings?
The Itinerary API returns the full booking details to the supplier who will provide the booked service. Suppliers that are not the service provider will receive a subset of the possible fields. These vary by the type of booking relative to the type of supplier. For example, Air booking suppliers that are not the supplier will not see the following fields:
- Vendor
- FlightNumber
- StartDateLocal
- StartDateUtc
How Can We Save Additional Charges for Hotel and Car Segments? What Types of Charges Are Supported?
The Charges element under Car and Hotel segments allow you to save additional charges using Semantics Codes. Refer to the Semantics and Vendor Codes sections under Reference for more information.
What Vendor Codes Can I Use When Sending Hotel and Car Segments?
Refer to the Semantics and Vendor Codes sections for the full list.
Can I View a Trip Posted Through the Itinerary API in the SAP Concur UI?
Yes. The user who owns the trip will see the trip on their home page. If the trip is in the future, it will show under the upcoming trip list. Trips that are ready to expense will show in the expense report list.
When Can a Trip Be Expensed?
Trips can be expensed after the trip is over under the following conditions:
- The trip has a Car, Hotel, or Ride segment.
- The trip has an Air segment with a ticket and the ticket has at least one valid ticket coupon, meaning the coupon is in one of the following statuses:
- OPEN
- USED
- PRTD
- StartDateUtc
Air segments can be expensed as soon as they have a ticket with a valid coupon, if the company uses the PreExpenseAir option.
Why is My New Booking Not Showing in the UI?
The request returned successfully with HTTP status - 200 OK. Posted bookings are automatically merged with any existing trip with overlapping dates. Most likely, a trip exists with the same dates and the booking has been added to it.
Will Posted Bookings Be Overwritten by Emailed or TripIt Trips?
No.
Will Posted Bookings Merge with Existing Cliqbook or TripIt Trips?
Yes.
Will Posted Trips Merge with Existing Trips?
No.
Best Practices
- When extracting past data:
- Extract a month of trip summaries to gauge volume. If hundreds are returned, then adjust extraction to weekly.
- Do not extract more than a year of data at any given time regardless of the volume. For longer look backs, extract six month segments maximum at a time.
- Do not multi-thread requests to retrieve multiple pages of data. Concurrent requests will impact your application’s performance.
- This API will only return itineraries that have been sent to Concur Travel; this includes travel booked within Concur Travel, TripIt, on TripLink supplier sites, plans emailed to Concur, and most bookings from your travel agency.
- Some customers may have multiple booking options, which may mean not all employee trips are available via this API. A good rule of thumb: if the traveler sees the itinerary in their “trips” list, then you can retrieve it from this API.
- Because the data comes from many sources, data across itineraries may not be consistent. It’s recommended that you only consume the relevant segments and data (for example, air only or air + hotel) for your application’s function.
- Itineraries change frequently. Changes do not necessarily indicate that the traveler modified their trip. You should address relevant changes only. This may mean comparing what your application considers relevant (for example, trip dates) across updated itineraries. In addition:
- If your application works with upcoming or in progress trips, be aware that you must evaluate the individual segments to determine whether it is a material change for your application.
- If your app is consuming itineraries before the trip occurs, cancellations should be taken into account. To incorporate cancelled trips, set the
includeCancelledtripsflag to “true” and leverage the trip status field to determine the application action.
- Your app should log key identifiers in addition to the
tripID. It is recommended that “client locator” and user UUID be tracked so you can troubleshoot issues and match to data that customers have available. - Many customers will opt-in to your integration for only a subset of their regions. It is recommended that you provide options, leveraging the user’s country in the travel profile, to determine which itineraries to extract.
- There are three different booking modes, all of which should be considered when building your application. Note that some clients additionally allow individuals to book for multiple passengers at a time.
- An individual booking for themselves.
- An individual booking on behalf of another user (profiled user).
- An individual booking for a guest (non-profiled user).
Reference
The Itinerary Reference documentation includes the following reference information that can be used in conjunction with the Trip Resource API and Booking Resource API documentation. It includes the following reference topics:
- Itinerary Data Model
- Car Vendor Codes
- Hotel Vendor Codes
- Ride Vendor Codes
- Semantics Codes
- Time Zone Formats
Itinerary Data Model
The Itinerary data model defines data elements that are returned or sent when getting, creating, updating, or deleting trips and bookings with the /api/travel/trip/v1.1 and /api/travel/booking/v1.1 resources respectively.
Trips include all bookings in an itinerary whereas a booking includes only a specific segment of an itinerary. It includes the following elements:
- Root Elements
- Booking Elements
- AirfareQuotes Elements
- Passengers Elements
- AirlineTickets Elements
- Fixed Elements
- AirBooking Elements
- CarBooking Elements
- Hotel Booking Elements
- Dining Booking Elements
- Ride Booking Elements
- Rail Booking Elements
- Parking Booking Elements
- Travel Booking Elements
Root Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| id | String | Y | The unique identifier for the trip URI with encrypted ID. |
| ItineraryInfo | Y | Parent element with the information about an itinerary for the specified user. | |
| TripId | String | Y | Encrypted trip identifier value. |
| ItinLocator | String | Y | This element is obsolete and is supported only for backward compatibility. |
| BookedVia | String | The booking method for the trip. | |
| BookedByFirstName | String | Y | The first name of the person who booked the trip. |
| BookedByLastName | String | Y | The last name of the person who booked the trip. |
| HasOpenBookingPassive | String | ||
| CancelComments | String | Y | The comments provided if the itinerary is cancelled. Maximum length: 256 characters. |
| ClientLocator | String | ||
| TripLinkLocator | String | ||
| Comments | String | Y | (Description here). Maximum length 512 characters. |
| DateBookedLocal | DateTime | Y | The date the trip was booked, in the local time of the booking location. Format: YYYY-MM-DDThh:mm:ss |
| DateCreatedUtc | DateTime | Y | The date that this trip was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateModifiedUtc | DateTime | Y | The date when this trip was last modified in UTC format. Format: YYYY-MM-DDThh:mm:ss. |
| Description | String | Y | The description for this trip. Maximum length 512 characters. |
| EndDateLocal | DateTime | Y | The end date of the trip in the ending location’s timezone. Format: YYYY-MM-DDThh:mm:ss. |
| EndDateUtc | DateTime | Y | The end date of the trip, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| TravelRequestId | String | ||
| IsPersonal | Boolean | Y | Indicates whether this trip is for business or for leisure. Format: Business, Leisure |
| ProjectName | String | The name of the project assiciated with this trip. Maximum length 255 characters. | |
| StartDateLocal | DateTime | Y | The start date of the trip in the starting location’s timezone. Format: YYYY-MM-DDThh:mm:ss. |
| StartDateUtc | DateTime | Y | The date when this trip started in UTC format. Format: YYYY-MM-DDThh:mm:ss. |
| TripName | String | Y | Name of the trip. Maximum length 255 characters. |
| TripStatus | unsignedByte | Y | The status of the trip. This element only appears if the includeCanceledTrips query parameter is used in the request. |
| UserLoginId | Y | The user's login to SAP Concur. This element appears only when the OAuth token is associated with a SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard. | |
| Bookings | Array | Y | An array of bookings that contains a Booking child element for each included booking. |
| Custom Attributes | Array | ||
| RuleViolations | Array | N | The list of rule violations associated with the itinerary. This parent element contains a RuleViolation child element for each associated rule violation. |
Booking Elements
The Bookings parent element contains a Booking child element for each included booking. TripLink suppliers have access only to a subset of the Booking elements. The TripLink column indicates with a Y if a specific element is available for a TripLink supplier. Each booking element contains the following child elements:
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| BookingOwner | String | Y | Specifies the tool that supplied the booking to Concur Travel. The possible values are: ConcurTravel, OpenBookingEmail, AmadeusETravel, ConcurConnectAPI, OpenBookingSupplier and TripIt |
| BookingSource | String | Y | For TMCs: The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place. For TripLink suppliers: The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place. This could be a GDS, OTA, Vendor Code for Supplier website or Supplier Direct Connect API |
| Source | Y | This element is obsolete and is supported only for backward compatibility. | |
| DateBookedLocal | DateTime | Y | The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| DateCreatedUtc | DateTime | Y | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateModifiedUtc | DateTime | Y | The date the booking was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| FareExpiresEmailDatetimeUtc | DateTime | ||
| FormOfPaymentName | String | The name of the form of payment for the booking. | |
| FormOfPaymentType | String | The type of the form of payment. | |
| LastTicketDateUtc | DateTime | ||
| PassengerCount | Int | The total count of passengers for the booking. | |
| RecordLocator | String | Y | The unique identifier for the booking |
| RetrievedDateUtc | |||
| TicketMailingAddress | The mailing address for the booked ticket, if available. | ||
| TicketPickupLocation | The pickup location for the booked ticket, if available | ||
| TicketPickupNumber | The confirmation number to pick up the booked ticket, if available. | ||
| CreditCardType | String | The type of credit card (for example, Visa/Mastercard/etc.). | |
| CreditCardLastFour | String | The last four digits of credit card number. | |
| AirfareQuotes | Array | List of stored airfare quotes for this booking. For more information, see the AirFareQuotes Elements table. | |
| ItinSourceName | String | The itinerary source. Format: TravelSupplier | |
| AirlineTickets | Array | List of airline tickets for this booking. For more information, see the AirLine Tickets Elements table. | |
| Charges | Array | The charges for this booking. For more information, see the Charges Elements table later on this page. | |
| MiscChargeOrders | Array | An array of miscellaneous charge orders for this booking. This parent element has a MiscellaneousChargeOrders child element for each miscellaneous charge order associated with this booking. For information about the child elements, see the MiscellaneousChargeOrders Elements table later on this page. | |
| Passengers | Array | Y | This parent element contains a Passenger child element for each booked passenger. See the Passengers Elements table for more information about the child elements. |
| PassPrograms | List of Pass Programs for this booking. This parent element has a PassProgram child element for each pass program associated with the booking. For information about the child elements, see the PassProgram Elements table later on this page. | ||
| PhoneNumbers | List of Phone numbers associated with this booking. This parent element has a PhoneNumberData child element for each phone number associated with the booking. For information about the child elements, see the PhoneNumberData Elements table later on this page. | ||
| RailPayments | Array | List of Rail payments associated with rail segments in this booking. For information about the child elements in the array, see the RailPayments Elements table later on this page. | |
| Segments | Y | List of Segments in this booking. This parent element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Travel parent elements for the booking. The segments are described in the tables below, see Air Booking Elements, Car Booking Elements, Hotel Booking Elements, Dining Booking Elements, Ride Booking Elements, Parking Booking Elements, and Travel Booking Elements. | |
| Delivery | String | The method this booking was delivered. | |
| WaitListSegments | The segments that the traveler is waitlisted for this booking. | ||
| Warnings | The warnings associated with the booking. | ||
| WebAddresses | List of web addresses such as emails and pickup URLs associated with this booking. |
MiscellaneousChargeOrder Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| DateCreatedUtc | dateTime | The date the charge order was created, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateModifiedUtc | dateTime | The date the charge order was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| IssueDate | dateTime | The date the charge order was issued. Format: YYYY-MM-DDThh:mm:ss | |
| PlatingCarrierNumericCode | string | Part of the ticket number that indicates the airline code. This is a three digit number. For example: 001=American, 005=Continental, 006=Delta, 012=Northwest | |
| PlatingControlNumber | string | Part of the ticket number that indicates the ticket control number. Format: Ten digit number. | |
| TotalAmount | decimal | The total amount of charge orders for the ticket. | |
| TotalAmountCurrency | string | The 3-letter ISO 4217 currency code for the total charge order amount. |
PassProgram Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| Amount | decimal | The program amount. | |
| Name | string | The program name. | |
| Type | string | The program type. | |
| UserFirstName | string | The first name of the passenger. | |
| UserLastName | string | The last name of the passenger. |
PhoneNumberData Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| PassengerRPH | integer | Indicates the passenger to whom this phone number belongs. | |
| PhoneNumber | string | The passenger's phone number. | |
| Type | string | The type of phone number. | |
| Description | string | The description for the phone number. |
RailPayments Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| RailAdjustment | Type | The amount adjusted for a rail booking. For information about the RailAdjustment child elements, see the RailAdjustment Elements table later on this page. | |
| RailPayment | Type | The payment information for a rail booking. For information about the RailPayment child elements, see the RailPayment Elements table later on this page. |
RailAdjustment Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| AdjustmentDateTime | dateTime | ||
| AdjustmentDateTimeUTC | dateTime | ||
| AdjustmentType | string | ||
| DateCreatedUtc | dateTime | ||
| DateModifiedUtc | dateTime | ||
| TicketDocumentIdentifier | string | ||
| TotalAdjustment | decimal | ||
| TotalAdjustmentCurrency | string | ||
| Taxes | Array | This parent element contains a Tax child element for each rail adjustment tax. For more information, see the Tax Elements table later on this page. |
RailPayment Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| BaseFare | decimal | The base fare of the booking quote. | |
| BaseFareCurrency | string | The 3-letter ISO 4217 currency code for the total fare. | |
| DateCreatedUtc | dateTime | The date the quote was created, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateModifiedUtc | dateTime | The date the quote was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| IssueByDate | dateTime | The date the quote must be issued by. Format: YYYY-MM-DDThh:mm:ss | |
| IssueDateTime | dateTime | ||
| IssueDateTimeUTC | dateTime | ||
| TicketDocumentIdentifier | string | ||
| TicketType | string | ||
| TotalFare | decimal | The total price of the booking. | |
| TotalFareCurrency | string | The 3-letter ISO 4217 currency code for the total fare. | |
| RailCharges | array | The charges applied by the airline. This parent element contains a Fixed and a Tax child element for each fixed charge and tax from the airline. See the Fixed Elements table and the Tax Elements table. |
AirfareQuotes Elements
The AirfareQuotes parent element is an array that contains a Quote child element that contains the following child elements.
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| BaseFare | Decimal | ||
| BaseFareCurrency | String | ||
| BaseFareNuc | Decimal | ||
| BaseFareNucCurrency | String | ||
| DateCreatedUtc | DateTime | ||
| DateModifiedUtc | DateTime | ||
| Endorsements | String | ||
| IssueByDate | DateTime | ||
| TotalFare | Decimal | ||
| TotalFareCurrency | String | ||
| AirlineCharges | Array | This parent element contains a Fixed and a Percent child element for each fixed charge and percent of fixed charge associated with this airfare quote. For information about these child elements, see the Fixed Elements table and the Percent Elements table later on this page. |
Passengers Elements
The passenger parent element is the Passengers Element in Booking Elements. This parent element contains a Passenger child element for each booked passenger.
| Element Name | Data Type | Required/Optional | TripLink | Description |
|---|---|---|---|---|
| NameFirst | String | required | Y | The first name of the passenger. |
| NameLast | String | required | Y | The last name of the passenger. |
| NameMiddle | String | optional | Y | The middle name of the passenger. |
| NamePrefix | String | optional | Y | The name prefix of the passenger. |
| NameRemark | String | optional | Y | Additional details about the passenger's name. |
| NameSuffix | String | optional | Y | The name suffix of the passenger. |
| NameTitle | String | optional | Y | The title of the passenger. |
| TextName | String | optional | Y | The user's full name as entered in the booking tool if different from the name in the database. |
| FrequentTravelerProgram | String | optional | Y | Passenger's loyalty programs |
AirlineTickets Elements
The AirlineTickets parent element is an array that contains the following child elements.
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| AirlineAdjustmentType | Type | Any adjustment made to the booking. For information about the child elements of AirlineAdjustmentType, see the AirlineAdjustmentType Elements table later on this page. | |
| ManualAirlineTicket | Type | The manual airline ticket for the booking. For information about the child elements of ManualAirlineTicket, see the ManualAirlineTicket Elements table later on this page. | |
| AirlineTicket | Type | The airline ticket for the booking. For information about the child elements of AirlineTicket, see the AirlineTicket Elements table later on this page. |
AirlineAdjustmentType Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| AddCollectAmount | decimal | ||
| AdjustmentDateTime | dateTime | ||
| AdjustmentDateTimeUTC | dateTime | ||
| AdjustmentType | String | ||
| DateCreatedUtc | dateTime | ||
| DateModifiedUtc | dateTime | ||
| PassengerName | string | ||
| PlatingCarrierNumericCode | string | ||
| PlatingControlNumber | string | ||
| RecordLocator | string | ||
| TotalAdjustment | decimal | ||
| TotalAdjustmentCurrency | string | ||
| Taxes | Array |
ManualAirlineTicket Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| BaseFare | decimal | ||
| BaseFareCurrency | string | ||
| DateCreatedUtc | dateTime | ||
| DateModifiedUtc | dateTime | ||
| TotalFareTotalFareCurrency | decimal | ||
| AirlineCharges | array | The charges applied by the airline. This parent element contains a Fixed and a Tax child element for each fixed charge and tax from the airline. For information about these child elements, see the Fixed Elements table and the Tax Elements table later on this page. |
AirlineTicket Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| AddCollectAmount | decimal | ||
| AccountingLine | string | ||
| BaseFare | decimal | ||
| BaseFareCurrency | string | ||
| BaseFareNuc | decimal | ||
| BaseFareNucCurrency | string | ||
| ComparisonFare | decimal | ||
| ComparisonFareCurrency | string | ||
| DateCreatedUtc | dateTime | ||
| DateModifiedUtc | dateTime | ||
| Endorsements | string | ||
| InvoiceNumber | string | ||
| IssueDateTime | dateTime | ||
| IssueDateTimeUTC | dateTime | ||
| IssuingIataAgencyNumber | integer | ||
| IssuingPseudoCity | string | ||
| LinearFareConstructor | string | ||
| MasterTicketNumber | string | ||
| NameReference | string | ||
| PassengerName | string | ||
| PlatingCarrierNumericCode | string | ||
| PlatingControlNumber | string | ||
| ProgramCarrierCode | string | ||
| ProgramMembershipNumber | string | ||
| RecordLocator string | string | ||
| SabreDkNumber string | string | ||
| Ticketless | boolean | ||
| TicketType | string | ||
| TotalFare | decimal | ||
| TotalFareCurrency | string | ||
| TourIdentifier | string | ||
| AirlineCharges | array | A list of airline charges for this ticket. This parent element contains a Fixed child element for each fixed charge from the airline. For information about these child elements, see the Fixed Elements table later on this page. | |
| AirlineTicketCoupons | array | A list of coupons for this ticket. This parent element has an AirlineTicketCoupon child element for each coupon associated with this airline ticket. For information about these child elements, see the AirlineTicketCoupon Elements table later on this page. | |
| AirlineTicketExchanges | array | A list of exchanges for this ticket. This parent element has an AirlineTicketExchange child element for each exchange associated with this airline ticket. For information about these child elements, see the AirlineTicketExchange Elements table later on this page. | |
| AirlineTicketFareBreakups | array | A list of fare breakups for this ticket. This parent element has an AirlineTicketFareBreakup child element for each fare breakup associated with this airline ticket. For information about these child elements, see the AirlineTicketFareBreakup Elements table later on this page. |
AirlineTicketCoupons Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| ClassOfService | string | ||
| CouponNumber | unsignedByte | ||
| CouponStatus | string | ||
| EndCityCode | string | ||
| FlightNumber | string | ||
| NotValidAfterDate | dateTime | ||
| NotValidBeforeDate | dateTime | ||
| RateCode | string | ||
| StartCityCode | sring | ||
| StartDateLocal | dateTime | ||
| Status | string | ||
| TicketDesignator | string | ||
| Vendor | string |
AirlineTicketExchanges Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| Amount | decimal | ||
| AppliedSegment1 | unsignedByte | ||
| AppliedSegment10 | unsignedByte | ||
| AppliedSegment2 | unsignedByte | ||
| AppliedSegment3 | unsignedByte | ||
| AppliedSegment4 | unsignedByte | ||
| AppliedSegment5 | unsignedByte | ||
| AppliedSegment6 | unsignedByte | ||
| AppliedSegment7 | unsignedByte | ||
| AppliedSegment8 | unsignedByte | ||
| AppliedSegment9 | unsignedByte | ||
| Currency | string | ||
| OldRecordLocator | string | ||
| DateModifiedUtc | dateTime | ||
| PlatingCarrierNumericCode | string | ||
| PlatingControlNumber | string |
AirlineTicketFareBreakups Elements
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| BaseFare | decimal | ||
| BaseFareCurrency | sring | ||
| DateCreatedUtc | dateTime | ||
| DateModifiedUtc | dateTime | ||
| IssueByDate | dateTime | ||
| IssueDateTime | dateTime | ||
| IssueDateTimeUTC | dateTime | ||
| TicketDocumentIdentifier | string | ||
| TicketType | string | ||
| TotalFare | decimal | ||
| TotalFareCurrency | string | ||
| Taxes | array | The charges applied by the airline. This parent element contains a Fixed and a Tax child element for each fixed charge and tax from the airline. For more information, see the Fixed Elements table and the Tax Elements table later on this page. |
Fixed Elements
The Fixed element contains the following child elements.
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| Amount | Decimal | The total amount for the rate for the booking. | |
| Currency | String | The 3-letter ISO 4217 currency code for the total amount. | |
| Description | String | The description for the rate. | |
| IsPaid | Boolean | Whether the rate has been paid. Format: true/false. | |
| IsPrimary | Boolean | Indicates whether the charge is the Primary or Main rate. For example, if one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be primary. Format: true/false. | |
| SemanticsCode | String | Indicates the charge category for the line item. Refer to the Semantics Codes table for more information. | |
| SemanticsVendorType | String | The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail | |
| StartDateLocal | DateTime | The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss | |
| Vendor | String | The vendor for the booking charge. | |
| VendorChargeCode | String | The vendor's code for the charge |
Tax Elements
This Tax element contains the following child elements.
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| TaxAmount | Decimal | The amount of the tax. | |
| TaxType | String | The type of the tax. |
Percent Elements
The percent of fixed charges. This parent element contains the following child elements:
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| Amount | Decimal | The total amount for the rate for the booking. | |
| Currency | string | The 3-letter ISO 4217 currency code for the total amount. | |
| Description | sring | The description for the rate. | |
| IsPaid | boolean | Whether the rate has been paid. Format: true/false. | |
| IsPrimary | boolean | Indicates whether the charge is the Primary or Main rate. For example, if one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be primary. Format: true/false. | |
| SemanticsCode | string | Indicates the charge category for the line item. Refer to the Semantics Codes table for more information. | |
| SemanticsVendorType | string | The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail | |
| StartDateLocal | dateTime | The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss | |
| Vendor | string | The vendor for the booking charge. | |
| VendorChargeCode | string | The vendor's code for the charge |
CustomAttributes Elements
The CustomAttributes parent element contains a CustomAttribute child element with the following child elements.
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| Data | String | ||
| DisplayTitle | String | ||
| DisplayValue | String | ||
| Name | String | ||
| DataType | String | ||
| DisplayOnItinerary | Boolean | ||
| ExternalId | Int |
RuleViolations Elements
The RuleViolations element contains a list of rule violations associated with the itinerary. This parent element contains a RuleViolation child element for each associated rule violation. The RuleViolation element has the following child elements:
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
| BestGdsPrice | Decimal | ||
| BestGdsVendor | String | ||
| BestInternetPrice | Decimal | ||
| BestInternetVendor | String | ||
| CompanyReasonCode | String | ||
| CompanyRuleText | String | ||
| Currency | String | ||
| DateEntered | DateTime | ||
| EndCity | String | ||
| EndDate | DateTime | ||
| NumberOfStops | Int | ||
| QuotedPrice | Decimal | ||
| RuleAction | String | ||
| RuleName | String | ||
| SegmentType | String | ||
| SelectedOtherAmount | Decimal | ||
| SelectedOtherAmountType | String | ||
| StartCity | String | ||
| StartDate | DateTime | ||
| TariffPrice | Decimal | ||
| TravelerComments | String | ||
| VendorCode | String | ||
| VendorName | String |
AirBooking Elements
The Air Booking parent element is the Air Element in the Segments Array in Booking Elements. This parent element contains an Air Booking child element for each booked flight.
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| ClassOfService | string | The class of the booking. | |
| ConfirmationNumber | string | The record locator or confirmation number for the flight from the airline. | |
| EndCityCode | string | Y | The IATA airport code for the end city of the booking. |
| EndDateLocal | dateTime | Y | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss. For TripLink suppliers: The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
| FlightNumber | string | Y | The flight number for the booking. |
| StartCityCode | string | Y | The IATA airport code for the starting address for the booking. |
| StartDateLocal | dateTime | Y | The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss. For TripLink suppliers: The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
| Vendor | string | Y | |
| CancellationNumber | string | The cancellation number from the vendor. This field should be set when you cancel a segment. | |
| CancellationPolicy | string | The cancellation policy from the vendor. | |
| Charges | Parent Element | The charges for this booking. For more information, see the Charges Elements table later on this page. | |
| DateCancelledUtc | dateTime | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateCreatedUtc | dateTime | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateModifiedUtc | dateTime | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| EndDateUtc | dateTime | Y | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss. For TripLink suppliers: The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
| EndGate | string | Y | The arrival gate for the booking. For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
| EndTerminal | string | Y | The arrival terminal for the booking. For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
| LegId | string | The leg ID of the booking. Leg IDs do not change on a connection. For each unique leg ID in the trip, all flights subsequent to the first segment with the same leg ID are connections. | |
| Seats | Parent Element | The seats for the booking. This parent element contains an AirSeat element for each included seat. For more information, see the AirSeat Elements table later on this page. | |
| StartDateUtc | dateTime | Y | The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss. For TripLink suppliers:The time portion of this value will be set to T00:00:00 if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
| StartGate | string | Y | The departure gate for the booking. For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
| StartTerminal | string | Y | The departure terminal for the booking. For TripLink suppliers: Will not appear in the response if the request is from a TripLink - Open Booking Air supplier that does not own the booking. |
| Status | string | The GDS based booking status for the segment such as HK, HL, BK, etc. | |
| TimeZone | string | Y | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. |
| AircraftCode | string | The code for the aircraft type. | |
| Bags | string | The number of bags included in the booking. | |
| Cabin | string | The section of the airplane for the booking. | |
| CarbonEmissionLbs | decimal | The pounds of carbon emission for this booking. | |
| CarbonModel | integer | The model used to calculate the carbon emissions. | |
| CheckedBaggage | string | Whether the booking includes checked baggage. | |
| Duration | integer | The duration of the booked flight. | |
| ETicket | string | Whether the booking has an e-ticket. Format: Y/N | |
| IsOpenSegment | boolean | Whether the segment is open. Format: True/False | |
| IsPreferredVendor | integer | If the airline is marked as a preferred property by the company. Format: True/False | |
| CreditCardType | String | The type of credit card (for example, Visa/Mastercard/etc.). | |
| CreditCardLastFour | String | The last four digits of credit card number. | |
| IsUpgradeAllowed | boolean | Whether the booking can be upgraded. Format: True/False | |
| Meals | string | The meals included in the booking. | |
| Miles | integer | The number of miles included in the booking. | |
| Notes | string | Additional details about the booking. | |
| OpenSegment | string | Additional information about the open segment. | |
| OperatedByFlightNumber | string | Flight Number provided by the airline operating the flight on behalf of the booked airline. | |
| OperatedByVendor | sring | The airline operating the flight on behalf of the booked airline. | |
| OperatedByVendorName | string | The name of the airline operating the flight on behalf of the booked airline. | |
| Services | string | The services included in the booking. | |
| SpecialInstructions | string | Additional instructions regarding the booking. Max Length: 256 | |
| UpgradedDateTime | dateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss |
AirSeat Elements
| Element | Data Type | Description |
|---|---|---|
| PassengerRph | integer | The passenger assigned to the seat. |
| SeatNumber | string | The number of the seat. |
CarBooking Elements
The Car Booking parent element is the Car Element in the Segments Array in Booking Elements. This parent element contains a Car Booking child element for each booked car.
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| ConfirmationNumber | string | The confirmation number from the vendor. | |
| EndDateLocal | dateTime | Y | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| StartDateLocal | dateTime | Y | The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| Vendor | string | The two letter GDS vendor code. See the Car Vendor Codes table for car vendor codes. | |
| CancellationNumber | string | The cancellation number from the vendor. This field should be set when you cancel a segment. | |
| CancellationPolicy | string | The cancellation policy from the vendor. | |
| Charges | Parent Element | The charges for this booking. For more information, see the Charges Elements table. | |
| Currency | string | The 3-letter ISO 4217 currency code for the booking. | |
| DailyRate | decimal | The daily rate for the booking. | |
| DateCancelledUtc | dateTime | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateCreatedUtc | dateTime | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateModifiedUtc | dateTime | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| EndCityCode | string | Y | The IATA airport code for the ending address for the booking. |
| EndDateUtc | dateTime | Y | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndLatitude | string | The latitude for the ending location of the booking. | |
| EndLongitude | string | The longitude for the ending location of the booking. | |
| Notes | string | Additional information about the booking. | |
| PhoneNumber | string | The phone number for the user. | |
| RateCode | string | The rate code for the booking. | |
| StartCityCode | string | Y | The IATA airport code for the starting address for the booking. |
| StartDateUtc | dateTime | Y | The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| StartLatitude | string | The latitude for the starting location of the booking. | |
| StartLongitude | string | The longitude for the starting location of the booking. | |
| Status | string | The booking status. | |
| TimeZone | string | Y | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. |
| TotalRate | decimal | The total rate amount of the booking. | |
| VendorName | string | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. | |
| AirCondition | string | The character code that indicates if car has air conditioner. R for AC, N for No AC | |
| Body | string | The character code to indicate how many passengers the car can seat. B for 2-door, D for 4-door, F for Four-wheel drive, J for All Terrain, K for truck, L for Limo, P for pick-up, R for recreation, S for Sport, T for Convertible, V for Van, W for Wagon/Estate, X for special. | |
| Class | string | Character code to indicate the class of the car (for example, if it is economy, full size, compact, etc.). Varies by Vendor. C for compact, E for economy, F for full size, I for Intermediate, L for Luxury, M for Mini, P for Premium, S for Standard, X for special. | |
| DiscountCode | string | The discount code used by the company/TMC to get a discounted rate. | |
| CreditCardType | String | The type of credit card (for example, Visa/Mastercard/etc.). | |
| CreditCardLastFour | String | The last four digits of credit card number. | |
| DropoffCollectionAddress1 | string | The AddressLine1 for the dropoff address when the rental service offers dropoff. | |
| DropoffCollectionAddressType | string | ||
| DropoffCollectionCategory | string | ||
| DropoffCollectionCity | string | City for the dropoff address when the rental service offers dropoff. | |
| DropoffCollectionCityCode | string | The IATA airport code for the dropoff address when the rental service offers dropoff. | |
| DropoffCollectionCountry | string | The country for the dropoff address when the rental service offers dropoff. | |
| DropoffCollectionLatitude | string | The latitude for the dropoff address when the rental service offers dropoff. | |
| DropoffCollectionLongitude | string | The longitude for the dropoff address when the rental service offers dropoff. | |
| DropoffCollectionNumber | string | ||
| DropoffCollectionPhoneNumber | string | The phone number for the dropoff address when the rental service offers dropoff. | |
| DropoffCollectionPostalCode | string | The postal code for the dropoff address when the rental service offers dropoff. | |
| DropoffCollectionState | string | The state for the dropoff address when the rental service offers dropoff. | |
| EndAddress | string | The ending address for the booking. | |
| EndAddress2 | string | The ending address for the booking. | |
| EndCity | string | Y | The ending address for the booking. |
| EndCloseTime | string | The closing time for the dropoff location. | |
| EndCountry | string | Y | The ending address for the booking. |
| EndLocation | string | The dropoff location. | |
| EndOpenTime | string | The opening time of the dropoff location. | |
| EndPhoneNumber | string | The phone number of the dropoff location. | |
| EndPostalCode | string | The ending address for the booking. | |
| EndState | string | Y | The ending address for the booking. |
| FrequentTravelerId | string | The loyalty program ID for the user. | |
| IsUpgradeAllowed | boolean | Whether the booking can be upgraded. Format: True/False | |
| NumCars | unsignedByte | The number of cars rented. | |
| NumPersons | unsignedByte | The number of people including the driver that the rental is for. | |
| PickupDeliveryAddress1 | string | The AddressLine1 for the pickup address when the rental service offers pickup. | |
| PickupDeliveryAddressType | string | ||
| PickupDeliveryCategory | string | ||
| PickupDeliveryCity | string | The city for the pickup address when the rental service offers pickup. | |
| PickupDeliveryCityCode | string | The IATA airport code for the pickup address when the rental service offers pickup. | |
| PickupDeliveryCountry | string | The country for the pickup address when the rental service offers pickup. | |
| PickupDeliveryLatitude | string | The latitude for the pickup address when the rental service offers pickup. | |
| PickupDeliveryLongitude | string | The longitude for the pickup address when the rental service offers pickup. | |
| PickupDeliveryNumber | string | ||
| PickupDeliveryPhoneNumber | string | The phone number for the pickup address when the rental service offers pickup. | |
| PickupDeliveryPostalCode | string | The postal code for the pickup address when the rental service offers pickup. | |
| PickupDeliveryState | string | The state for the pickup address when the rental service offers pickup. | |
| RateType | string | The rate type for the booking. | |
| SpecialEquipment | string | Any special equipment required by the renter. | |
| SpecialInstructions | string | Additional instructions regarding the booking. Max Length: 256 | |
| StartAddress | string | The starting address of the booking. | |
| StartAddress2 | string | The starting address for the booking. | |
| StartCity | string | Y | The starting address for the booking. |
| StartCloseTime | string | The closing time for the pickup location. | |
| StartCountry | string | Y | The starting address for the booking. |
| StartLocation | string | The starting location of the booking. | |
| StartOpenTime | string | The opening time for the pickup location. | |
| StartPostalCode | string | The starting address for the booking. | |
| StartState | string | Y | The starting address for the booking. |
| Transmission | string | The character code that indicates if the car has auto-transmission. A for Auto, M for Manual | |
| UpgradedDateTime | dateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss |
Hotel Booking Elements
The Hotel Booking parent element is the Hotel Element in the Segments Array in Booking Elements. This parent element contains a Hotel Booking child element for each booked hotel.
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| ConfirmationNumber | string | The confirmation number from the vendor. | |
| EndDateLocal | dateTime | Y | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| Name | string | The hotel name for the booking. | |
| StartCityCode | string | Y | The IATA airport code for the starting address for the booking. |
| StartDateLocal | dateTime | Y | The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| Status | string | Y | The booking status. |
| Vendor | string | The two letter GDS vendor code. See the Hotel Codes table for hotel vendor codes. | |
| CancellationNumber | string | The cancellation number from the vendor. This field should be set when you cancel a segment. | |
| CancellationPolicy | string | The cancellation policy from the vendor. | |
| Charges | Parent Element | The charges for this booking. For more information, see the Charges Elements table. | |
| CheckinTime | string | The check in time for the hotel booking. | |
| CheckoutTime | string | The check out time for the hotel booking. | |
| Currency | string | The 3-letter ISO 4217 currency code for the booking. | |
| CreditCardType | String | The type of credit card (for example, Visa/Mastercard/etc.). | |
| CreditCardLastFour | String | The last four digits of credit card number. | |
| DailyRate | decimal | Average per day rate for the hotel. If the rate varies over the duration, it can be specified using the charges model. | |
| DateCancelledUtc | dateTime | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateCreatedUtc | dateTime | Y | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateModifiedUtc | dateTime | Y | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndDateUtc | dateTime | Y | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| HotelPropertyId | string | The hotel's property ID. | |
| Notes | string | Additional information about the booking. | |
| NumPersons | unsignedByte | The number of people the booking is for. | |
| NumRooms | unsignedByte | The number of rooms the booking is for. | |
| PhoneNumber | string | The phone number for the booking. | |
| RateCode | string | The rate code for the booking. | |
| RoomDescription | string | The room description for the booking. Max Length: 200 | |
| RoomType | string | The room type for the booking. | |
| SpecialInstructions | string | Additional instructions regarding the booking. Max Length: 256 | |
| StartAddress | string | The starting address of the booking. | |
| StartAddress2 | string | The starting address for the booking. | |
| StartCity | string | Y | The starting address for the booking. |
| StartCountry | string | Y | The starting address for the booking. |
| StartLatitude | string | The latitude for the starting location of the booking. | |
| StartLongitude | string | The longitude for the starting location of the booking. | |
| StartPostalCode | string | The starting address for the booking. | |
| StartState | string | The starting address for the booking. | |
| StartDateUtc | dateTime | Y | The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| TimeZone | string | Y | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. |
| TotalRate | string | The total rate amount of the booking. | |
| EndCityCode | string | The IATA airport code for the ending address for the booking. | |
| DiscountCode | string | The discount code for the booking. | |
| FrequentTravelerId | string | The traveler’s ID for the frequent traveler reward program. | |
| HadDeposit | boolean | Whether the booking had a deposit. Format: true/false | |
| IsUpgradeAllowed | boolean | Whether the booking can be upgraded. Format: true/false | |
| ModificationCode | string | The code for the modification to the booking. | |
| PartnerMembershipId | string | The membership ID of the partner associated with the booking. | |
| PassiveType | string | The type of the booking. | |
| RateAccess | string | The rate access for the booking. | |
| RateType | string | The rate type for the booking. | |
| UpgradedDateTime | dateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss | |
| VendorFlags | string | Semi-colon-delimited list of flags for free hotel service flags. For example, free breakfast (FB), internet (FI), Parking (FP), etc. If they were all present they can be concatenated as - FB;FI;FP; | |
| VendorName | string | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
Dining Booking Elements
The Dining Booking parent element is the Dining Element in the Segments Array in Booking Elements. This parent element contains a Dining Booking child element for each booked meal.
| Element | Date Time | TripLink | Description |
|---|---|---|---|
| ConfirmationNumber | string | The confirmation number from the vendor. | |
| CancellationNumber | string | The cancellation number from the vendor. This field should be set when you cancel a segment. | |
| Charges | Parent Element | The charges for this booking. For more information, see the Charges Elements table later on this page. | |
| DateCancelledUtc | dateTime | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateCreatedUtc | dateTime | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateModifiedUtc | dateTime | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| EndDateLocal | dateTime | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss | |
| EndDateUtc | dateTime | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| FrequentTravelerId | string | The loyalty program ID for the user. | |
| IsUpgradeAllowed | boolean | Whether the booking can be upgraded. Format: true/false | |
| Name | string | The name of the restaurant. Maximum length: 80 | |
| Notes | string | Additional information about the booking. | |
| NumPersons | unsignedByte | The number of persons for the booking. | |
| PhoneNumber | string | The restaurant phone number. | |
| RestaurantId | string | The booking vendor’s restaurant ID. Maximum length: 50 | |
| StartAddress | string | The restaurant address. Maximum length: 80 | |
| StartAddress2 | string | The restaurant address. Maximum length: 80 | |
| StartCity | string | The restaurant address. Maximum length: 50 | |
| StartCountry | string | The restaurant address. | |
| StartDateLocal | dateTime | The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss | |
| StartDateUtc | dateTime | The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| StartLatitude | string | The latitude of the restaurant. | |
| StartLongitude | string | The longitude of the restaurant. | |
| StartPostalCode | string | The restaurant address. Maximum length: 24 | |
| StartState | string | The restaurant address. Maximum length: 50 | |
| Status | string | The status of the segment. | |
| TimeZone | string | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. | |
| UpgradedDateTime | dateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss | |
| Vendor | string | The two letter GDS vendor code. | |
| VendorName | string | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
Ride Booking Elements
The Ride Booking parent element is the Ride Element in the Segments Array in Booking Elements. This parent element contains a Ride Booking child element for each booked ride.
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| ConfirmationNumber | string | The confirmation number from the vendor. | |
| EndCityCode | string | The ending IATA airport code of the booking. | |
| StartCityCode | string | The starting IATA airport code of the booking. | |
| Vendor | string | The two letter GDS vendor code. See the Ride Codes table for ride vendor codes. For an unknown vendor, use the code value $$. | |
| CancellationNumber | string | The cancellation number from the vendor. This field should be set when you cancel a segment. | |
| CancellationPolicy | string | The cancellation policy from the vendor. | |
| Currency | string | The 3-letter ISO 4217 currency code for the booking. | |
| DateCancelledUtc | dateTime | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateCreatedUtc | dateTime | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateModifiedUtc | dateTime | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DropoffInstructions | string | Instructions regarding the booking. | |
| Duration | integer | The duration of the booking. | |
| EndAddress | string | The ending address of the booking. | |
| EndAddress2 | string | The ending address of the booking. | |
| EndCity | string | The ending address of the booking. | |
| EndCountry | string | The ending address of the booking. | |
| EndDateLocal | dateTime | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss | |
| EndDateUtc | dateTime | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| EndLatitude | string | The latitude for the ending location of the booking. | |
| EndLocation | string | The ending location of the booking. | |
| EndLocationCode | string | The ending location code of the booking. | |
| EndLocationName | string | The ending location name of the booking. | |
| EndLongitude | string | The longitude of the ending point of the booking. | |
| EndPostalCode | string | The ending address of the booking. | |
| EndState | string | The ending address of the booking. | |
| IsPersonal | boolean | Whether the segment is for personal travel. Format: true/false. | |
| IsUpgradeAllowed | boolean | Whether the booking can be upgraded. Format: true/false | |
| MeetingInstructions | string | The instructions for the meeting location of the booking. | |
| Miles | integer | The number of miles for the booking. | |
| Name | string | The name on the booking. | |
| Notes | string | Additional information about the booking. | |
| NumberOfHours | double | The number of hours of the booking. | |
| NumPersons | unsignedByte | The number of people included in the booking. | |
| OperatedByVendor | string | The operated by vendor for the booking. | |
| PassiveCityCode | string | The passive city code of the booking. | |
| PhoneNumber | string | The ride vendor phone number. | |
| PickupInstructions | string | Instructions regarding the booking. | |
| Rate | string | The rate for the booking. | |
| RateDescription | string | The rate description for the booking. | |
| RateNotes | string | The rate notes for the booking. | |
| RateType | string | The rate type for the booking. | |
| ReservationId | string | The booking vendor’s reservation ID. | |
| SpecialInstructions | string | The special instructions for the ride. Max Length: 256 | |
| StartAddress | string | The starting address of the booking. | |
| StartAddress2 | string | The starting address of the booking. | |
| StartCity | string | The starting address of the booking. | |
| StartCountry | string | The starting address of the booking. | |
| StartDateLocal | dateTime | The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss | |
| StartDateUtc | dateTime | The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| StartLatitude | string | The latitude of the booking start location. | |
| StartLocation | string | The starting location of the booking. | |
| StartLocationCode | string | The code of the starting location of the booking. | |
| StartLocationName | string | The name of the starting location of the booking. | |
| StartLongitude | string | The longitude of the booking start location. | |
| StartPostalCode | string | The starting address of the booking. | |
| StartState | string | The starting address of the booking. | |
| Status | string | The status of the segment. | |
| TimeZone | string | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. | |
| UpgradedDateTime | dateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss | |
| VendorName | string | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. | |
| Charges | Parent Element | The charges for this booking. For more information, see the Charges Elements table. |
Rail Booking Elements
The Rail Booking parent element is the Rail Element in the Segments Array in Booking Elements. This parent element contains a Rail Booking child element for each booked rail segment.
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| ConfirmationNumber | string | The confirmation number from the vendor. | |
| StartDateLocal | dateTime | Y | The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss |
| Amenities | string | The booked amenities. | |
| Cabin | string | The cabin identifier. | |
| CancellationNumber | string | The cancellation number from the vendor. This field should be set when you cancel a segment. | |
| CarbonEmissionLbs | decimal | The pounds of carbon emission for this booking. | |
| CarbonModel | integer | The model used to calculate the carbon emissions. | |
| ClassOfService | string | The class of the booking. | |
| CreditCardType | String | The type of credit card (for example, Visa/Mastercard/etc.). | |
| CreditCardLastFour | String | The last four digits of credit card number. | |
| Currency | string | The 3-letter ISO 4217 currency code for the booking. | |
| DateCancelledUtc | dateTime | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateCreatedUtc | dateTime | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateModifiedUtc | dateTime | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DiscountCode | string | The discount code for the booking. | |
| Duration | integer | The duration of the trip booked. | |
| EndCity | string | The end city for the rail trip. | |
| EndCityCode | string | The IATA airport code for the end city of the trip. | |
| EndCountry | string | The country code for the booking. | |
| EndDateLocal | dateTime | Y | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| EndDateUtc | dateTime | Y | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndLatitude | string | The latitude of the ending point of the booking. | |
| EndLongitude | integer | The longitude of the ending point of the booking. | |
| EndPlatform | string | The ending platform location of the booking. | |
| EndRailStation | string | Y | The code for the ending station of the booking. |
| EndRailStationName | string | Y | The name of the ending station of the booking. |
| ETicket | integer | The e-ticket number. | |
| FareType | string | The type of fare on the rail booking. | |
| FrequentTravelerId | string | The traveler’s ID for the frequent traveler reward program. | |
| IsUpgradeAllowed | boolean | Whether the booking can be upgraded. Format: true/false | |
| LegId | string | The trip leg ID. | |
| Meals | string | The booked meals. | |
| Miles | integer | The number of miles booked. | |
| Notes | string | Additional information about the booking. | |
| NumPersons | unsignedByte | The number of persons booked for the trip. | |
| NumStops | unsignedByte | The number of stops in the booking. | |
| OperatedByTrainNumber | string | The train identifier of the operating vendor of the booked trip. | |
| OperatedByVendor | string | The operating vendor of the booked trip. | |
| RateCode | string | The vendor's code for the rate of the booking. | |
| RouteRestrictCode | string | The code to restrict the route of the booking. | |
| SpecialInstructions | string | The instructions for the booking. Max Length: 256 | |
| StartCity | string | The starting city of the booking. | |
| StartCityCode | string | Y | The IATA airport code for the starting city of the booking. |
| StartCountry | string | The starting country of the booking. | |
| StartDateUtc | dateTime | Y | The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| StartLatitude | string | The latitude of the starting location of the booking. | |
| StartLongitude | string | The longitude of the starting location of the booking. | |
| StartPlatform | string | The starting platform location of the booking. | |
| StartRailStation | string | Y | The code of the starting station of the booking. |
| StartRailStationName | string | Y | The name of the starting station of the booking. |
| Status | string | The booking status. | |
| TimeZone | string | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. | |
| TotalRate | decimal | The total rate amount of the booking. | |
| TrainNumber | string | The number for the booked train. | |
| TrainTypeCode | string | The code for the type of train used in the booking. | |
| TrainTypeName | string | The name of the type of train used in the booking. | |
| TransportMode | sring | The transport mode of the booking. | |
| UpgradedDateTime | dateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss | |
| Vendor | string | The two letter GDS vendor code. | |
| VendorName | string | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. | |
| WagonNumber | string | The wagon number of the train car. | |
| Charges | Parent Element | The charges for this booking. For more information, see the Charges Elements table. | |
| Seats | Parent Element | The booked seats. This parent element contains a RailSeat element for each included seat. For more information, see the RailSeat Elements table later on this page. |
RailSeat Elements
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| Amenities | string | The amenities for the seat. | |
| BerthPosition | string | The berth location of the seat. | |
| Deck | string | Which deck the seat is on. | |
| FacingForward | string | Whether the seat is facing forward. | |
| FareSpaceComfort | string | The space around the seat. | |
| PassengerRph | integer | Which passenger the seat is assigned to. | |
| SeatNumber | string | The number of the seat. | |
| SeatPosition | string | The location of the seat. | |
| SpaceType | string | The type of space around the seat. | |
| Status | string | The status of the seat booking. | |
| WagonNumber | string | The number of the wagon the seat is on. | |
| WagonType | string | The type of wagon the seat is on. |
Parking Booking Elements
The Parking Booking parent element is the Parking Element in the Segments Array in Booking Elements. This parent element contains a Parking Booking child element for each booked parking.
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| ConfirmationNumber | string | The confirmation number from the vendor. | |
| StartDateLocal | dateTime | The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss | |
| CancellationNumber | string | The cancellation number from the vendor. This field should be set when you cancel a segment. | |
| ClassOfService | string | The class of the booking. | |
| Currency | string | The 3-letter ISO 4217 currency code for the booking. | |
| DateCancelledUtc | dateTime | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateCreatedUtc | dateTime | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateModifiedUtc | dateTime | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| EndDateLocal | dateTime | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss | |
| EndDateUtc | dateTime | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| FrequentTravelerId | string | The traveler’s ID for the frequent traveler reward program. | |
| IsUpgradeAllowed | boolean | Whether the booking can be upgraded. Format: true/false | |
| Notes | string | Additional information about the booking. | |
| OperatedByVendor | string | The operating vendor of the booking. | |
| ParkingLocationId | string | The location of the parking booking. | |
| PhoneNumber | string | The parking phone number. | |
| Pin | string | The PIN number for the booking. | |
| RateCode | string | The vendor's code for the rate of the booking. | |
| StartAddress | string | The starting address of the booking. | |
| StartAddress2 | string | The starting address of the booking. | |
| StartCity | string | The starting address of the booking. | |
| StartCityCode | string | The IATA airport code for the starting city of the booking. | |
| StartCountry | string | The starting address of the booking. | |
| StartDateUtc | dateTime | The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| StartLocation | string | The parking location. | |
| StartPostalCode | string | The starting address of the booking. Maximum length: 24 | |
| StartState | string | The starting address of the booking. Maximum length: 50 | |
| Status | string | The booking status. | |
| TimeZone | string | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. | |
| TotalRate | string | The total rate amount of the booking. | |
| UpgradedDateTime | dateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss | |
| Vendor | string | The two letter GDS vendor code. | |
| VendorName | string | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. | |
| Charges | Parent Element | The charges for this booking. For more information, see the Charges Elements table later on this page. |
Travel Booking Elements
The Travel Booking parent element is the Travel Element in the Segments Array in Booking Elements. This parent element contains a Travel Booking child element for each booked travel request.
NOTE: This booking type is used by the Concur Travel Request product to store the main destination for the trip without specifying a transport type.
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| CancellationNumber | string | The cancellation number from the vendor. This field should be set when you cancel a segment. | |
| ConfirmationNumber | sring | The confirmation number from the vendor. | |
| CreditCardType | String | The type of credit card (for example, Visa/Mastercard/etc.). | |
| CreditCardLastFour | String | The last four digits of credit card number. | |
| Currency | string | The 3-letter ISO 4217 currency code for the booking. | |
| DailyRate | decimal | Average per day rate for the booking. If the rate varies over the duration, it can be specified using the charges model. | |
| DateCancelledUtc | dateTime | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateCreatedUtc | dateTime | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| DateModifiedUtc | dateTime | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| EndAddress | string | The ending address of the booking. | |
| EndAddress2 | sring | The ending address of the booking. | |
| EndCity | string | The ending address of the booking. | |
| EndCityCode | string | The IATA airport code for the ending city of the booking. | |
| EndCountry | string | The ending address of the booking. | |
| EndDateLocal | dateTime | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss | |
| EndDateUtc | dateTime | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| EndLatitude | string | The latitude for the ending location of the booking. | |
| EndLocation | sring | The ending location of the booking. | |
| EndLongitude | string | The longitude of the ending point of the booking. | |
| EndPostalCode | string | The ending address of the booking. | |
| EndState | sring | The ending address of the booking. | |
| TransportMode | string | The transport mode of the booking. | |
| Notes | string | Additional information about the booking. | |
| NumPersons | unsignedByte | The number of persons booked for the trip. | |
| PhoneNumber | string | The booking phone number. | |
| SpecialInstructions | sring | The instructions for the booking. Max Length: 256 | |
| StartAddress | string | The starting address of the booking. | |
| StartAddress2 | string | The starting address of the booking. | |
| StartCity | sring | The starting address of the booking. | |
| StartCityCode | string | The IATA airport code for the starting city of the booking. | |
| StartCountry | string | The starting address of the booking. | |
| StartDateLocal | dateTime | The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss | |
| StartDateUtc | dateTime | The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss | |
| StartLatitude | string | The latitude of the booking. | |
| StartLongitude | sring | The longitude of the booking. | |
| StartPostalCode | string | The starting address of the booking. Maximum length: 24 | |
| StartState | string | The starting address of the booking. Maximum length: 50 | |
| Status | string | The booking status. | |
| TimeZone | sring | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. | |
| TotalRate | decimal | The total rate amount of the booking. | |
| Vendor | string | The two letter GDS vendor code. | |
| VendorName | string | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. | |
| Charges | Parent Element | The charges for this booking. For more information, see the Charges Elements table. |
Charges Elements
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| Percent | Parent Element | The percent of fixed charges. For more information about the child elements of this parent element, see the Percent Elements table. | |
| Fixed | Parent Element | The fixed charges. For more information about the child elements of this parent element, see the Fixed Elements table. | |
| Rate | Parent Element | The rate for the booking. For more information about the child elements of this parent element, see the Rate Elements table. | |
| RateWithAllowance | Parent Element | The rate for the booking, including any travel allowances. For more information about the child elements of this parent element, see the RateWithAllowance Elements table. |
Rate Elements
| Element | Data Type | Description | |
|---|---|---|---|
| Amount | decimal | The total amount for the rate for the booking. | |
| Currency | string | The 3-letter ISO 4217 currency code for the total amount. | |
| Description | string | The description for the rate. | |
| IsPaid | boolean | Whether the rate has been paid. Format: true/false. | |
| IsPrimary | boolean | Whether the rate is primary. Format: true/false. | |
| NumUnits | decimal | The number of units expected for the charge. For instance, 3 days | |
| PerUnit | string | The unit of measure for the charge. Values represent rates like per DAY, WEEK, or MONTH | |
| SemanticsCode | string | Indicates the charge category for the line item. Refer to the Semantics Codes table for more information. | |
| SemanticsVendorType | string | The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail | |
| StartDateLocal | dateTime | The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss | |
| Vendor | string | The vendor for the booking charge. | |
| VendorChargeCode | string | The vendor's code for the charge. |
RateWithAllowance Elements
| Element | Data Type | TripLink | Description |
|---|---|---|---|
| AllowanceAmount | decimal | The cost of overage fees when the allowance is exceeded. For example, if the allowance is 5000 miles, the cost could be $0.02 per mile. The overage must be in the same currency as the basic rate. | |
| AllowanceIsUnlimited | boolean | Whether the allowance is unlimited. Format: true/false. | |
| AllowanceNumUnits | decimal | The number of units for the allowance associated with the charge. For example, 5000 miles. | |
| AllowanceUnit | string | The unit of measure for the allowance associated with the charge. For example, a car weekly rate might allow 5000 miles included in the rate. | |
| Amount | decimal | The total amount for the rate for the booking. | |
| Currency | string | The 3-letter ISO 4217 currency code for the total amount. | |
| Description | string | The description for the rate. | |
| IsPaid | boolean | Whether the rate has been paid. Format: true/false. | |
| IsPrimary | boolean | Indicates whether the charge is the Primary or Main rate. For example, if one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be primary. Format: true/false. | |
| NumUnits | decimal | The number of units expected for the charge. For instance, 3 days. | |
| PerUnit | string | The unit of measure for the charge. Values represent rates like per DAY, WEEK, or MONTH | |
| SemanticsCode | string | Indicates the charge category for the line item. Refer to the Semantics Codes table for more information. | |
| SemanticsVendorType | string | The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail | |
| StartDateLocal | dateTime | The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss | |
| Vendor | string | The vendor for the booking charge. | |
| VendorChargeCode | string | The vendor's code for the charge. |
Car Vendor Codes
The following car vendor codes are used in the Car Booking Elements.
| Vendor Code | Vendor Name |
|---|---|
| FA | Able |
| AC | Ace |
| AD | Advantage |
| AL | Alamo |
| LV | Allstate |
| AF | Americar |
| ZU | AutoEurope |
| ZI | Avis |
| CH | Charlie |
| CP | Compass |
| CO | Continental |
| DS | Discount |
| ZR | Dollar |
| ET | Enterprise |
| ED | Eurodollar |
| EP | Europcar |
| FH | Falles Hire Cars |
| FD | Ford Dealer |
| HO | Holiday Car |
| IM | Imperial |
| IA | Independent Auto |
| TS | Intl Travel |
| KG | Kemwel Holiday |
| KN | Kenning |
| LL | Localiza |
| ZW | Montgomery Ward |
| NE | Nationwide |
| ZA | Payless |
| PI | Pinellas |
| BL | Red And Blue |
| RR | Rent Rite |
| RS | Resort |
| ZS | Sears |
| SX | Sixt |
| ZT | Thrifty |
| CC | Country Car |
| TR | Triangle |
| CT | TT/Key Services |
| SV | U-Save |
| CY | Carey International |
| CV | Capps Vans |
| AB | All American |
| EE | Exoticar Express |
| LX | Limo Service |
| MW | Midway |
| NF | New Frontier |
| SL | SL I.T.S. |
| US | US Rent a Car |
| VR | Specialty Van |
| WC | West Coast |
| ZH | Simply Wheelz |
| NU | Nu Car Rentals |
| EY | Economy Rent a Car |
| $$ | Unknown Car Vendor |
| ZM | Zoom Rent a Car |
| ZD | Budget |
| ZE | Hertz |
| ZL | National |
| AU | Austrian |
| DR | DER Travel Svcs |
| EN | Vip Car Rental |
| ML | Merlin |
| EZ | Ez Rent A Car |
| FX | Fox |
| LM | L & M Car Rental |
| SW | Southwest |
| NW | New Frontier |
Hotel Vendor Codes
| Vendor Code | Vendor Name |
|---|---|
| RT | AccorHotels |
| AM | Adams Mark |
| AZ | The Ascott Limited |
| AS | All Suites |
| AR | AC Hoteles |
| AJ | AmeriSuites |
| AN | Ana Hotels |
| AX | Anasazi Service |
| AQ | ATA Hotels |
| AO | Atlantis Hotel |
| AH | Aston Hotels |
| AP | Andre Balazs |
| AC | Atel France |
| BB | Bartell Hotels |
| BW | Best Western |
| BM | Biltmore |
| BU | Baymont Inns |
| CJ | Caesar Park |
| QC | Camberly |
| CA | Confortel |
| CO | Camino Real Htls |
| CV | COMO Hotels and Resorts |
| CE | Chalet Susse |
| CR | Clarion |
| CH | CIH Hotels |
| WX | Coast Hotels |
| CS | Classical Hotels |
| CI | Comfort Inns |
| CD | Concord Hotels |
| WA | Waldorf Astoria |
| BC | Boutiquw |
| CX | Country Inn |
| CL | Corus Hotels |
| DC | Dorchester Htls |
| DE | Delta Hotels |
| DS | Design Hotels |
| FT | Grande Hotels |
| DV | De Vere |
| DA | Doral Hotels |
| DO | Dorintresorts |
| DT | Doubletree |
| DY | Doyle Hotels |
| DR | Drury Inns |
| EE | Marriott Exec Ap |
| EO | Econo Lodge |
| ER | Electronic Rep |
| EU | Exclusive Htls |
| RM | Hetras |
| XH | Extra Holidays |
| FA | Fairmont Hotels |
| FQ | Fauriel |
| FM | Fiesta American |
| FE | Forte Hotels |
| FS | Four Seasons |
| FZ | Friendship Inns |
| FC | Rocco Forte |
| GX | Global Conextion |
| HN | Linkhotel |
| GR | Six Senses Hotel |
| GT | Golden Tulip |
| AG | Gouverner Hotel |
| GN | Gramercy Park Hotel |
| GH | Grand Heritage |
| GD | Grand Tradition |
| HB | Hbs Hotel Booki |
| HX | Hampton Inns |
| HR | Harrah's |
| HV | Harvey Hotels |
| HP | Hyatt Place |
| BH | Hawthorn Suites |
| HL | Hilton Intl |
| BE | Homestead Studio |
| HG | Homewood Suites |
| HO | Hotelrez |
| AI | Armani Hotels |
| HW | Hotel World |
| HQ | Hotelink Intl |
| HA | HOTUSA Hotels |
| MR | Morgans Hotel Group |
| IL | Innlink Res Svc |
| IP | InnPoints |
| IG | Insignia Resorts |
| IC | InterContinental |
| IE | InterEurope Htls |
| IT | Intl Trvl Resort |
| TS | Intl Trvl Svcs |
| IR | Innpoints |
| JA | Jarvinen Hotels |
| JY | Jolly Hotels |
| KA | Karos Hotels |
| KI | Kempinski |
| KY | Keytel |
| KC | Kimpton Hotels |
| KN | Kintetsu Intl |
| NV | Las Vegas Travel |
| LW | Leading Hotels |
| LM | Vantis Hotel GRP |
| LA | Little America |
| LZ | Loews Hotels |
| LR | LRI |
| LU | Luxor Hotel |
| MY | Personality Hotels |
| MZ | Mainstay Suites |
| MO | Mandarin Orientl |
| MH | Marco Polo Htls |
| MM | Maritim Hotels |
| ET | Marriott Cnf Ctr |
| MG | Magnolia Hotels |
| MF | Micros Fidelio |
| MT | Microtel Hotels |
| MU | Millennium Htls |
| MP | Mantra Group |
| MN | Montage Hotels A |
| MI | Malmaison Hotels |
| MK | Movenpick Htls |
| ND | National Hotels |
| NO | New Otani |
| NK | Nikko Hotels |
| NH | Nippon Travel |
| OB | Oberoi Group |
| OC | Okura Hotels |
| OM | Omni Hotels |
| OH | Oslo Hotel |
| OR | Outrigger |
| PS | Sandman Hotels |
| PF | Pan Pacific |
| PL | Parkroyal Hotels |
| PQ | Purple Hotels |
| PH | Preferred Hotels |
| PW | Prima Hotels |
| PN | Peninsula Hotels |
| PR | Protea Hotels |
| QI | Quality Inns |
| QL | Queens Hotels |
| QM | Queens Moat Htls |
| QH | QHotels |
| RD | Radisson |
| NR | Ramada Intl |
| ON | Reconline |
| RL | Red Lion Inns |
| RF | Red Roof Inns |
| RQ | Regal Hotels |
| KR | Regal Hotels UK |
| RE | Regent Intl |
| RH | Reservations Hub |
| BR | Renaissance Intl |
| RC | Residence Inns |
| RR | Righa Royal |
| RZ | Ritz-Carlton |
| RW | Rosewood |
| RI | Rodeway Inns |
| RO | Rotana Hotels and Resorts |
| RB | Resort Bookings |
| RG | Rydges Group |
| SH | Scandic Hotels |
| IQ | Myfidelio |
| SC | Sceptre Hotels |
| SQ | Select Hotels |
| SG | Shangri-La |
| BP | Shilo Inns |
| US | Sierra Hotels |
| SJ | Jameson Inns |
| SZ | Sleep Inns |
| SB | Sofitel |
| LX | Small Luxury |
| SM | InnLink Res Svc |
| SN | Sonesta Hotels |
| ST | Sorat Hotels |
| SP | Special Prop-IHG |
| XV | SpringHill Suites |
| SR | Steigenberger |
| SK | Stakis Hotels |
| YS | Stamford Hotels |
| LV | Las Vegas Test |
| YZ | Staybridge Ste |
| WR | Sterling Intl |
| SS | Studio 6 |
| XL | Summit Hotels |
| SX | Supranational |
| UK | Swallow Hotels |
| SL | Swissotel |
| TI | Thistle Hotels |
| TM | Tianma |
| TP | Top Intnl Htls |
| TH | Trident Hotels |
| TO | TownePlace Suites |
| TA | Reservhotel |
| TX | Treff Hotels |
| TR | Cendant Trip Rewards |
| VP | VIP Intl |
| VA | OneTech Solution |
| VI | Vienna International |
| WH | W Hotels |
| DW | Walt Disney Htl |
| WK | Warwick Hotels |
| WL | Wellesley Inns |
| WM | Westmark Hotel |
| EJ | Williams |
| WC | WestCoast Hotels |
| WW | World Hotels |
| WY | Wyndham Hotels |
| SW | Starwood (All) |
| AL | Aloft Hotels |
| BY | Banyan Tree |
| EL | Elements |
| GA | Global Alliance |
| IW | Hotels & Preference |
| QX | Luxury Lifestyle |
| RP | Rendezvous Hospitality Group |
| RU | Hard Rock |
| TY | Tradyso Global Distribution |
| ZX | Marriott Affliat |
| TB | GTA TravelBound |
| DX | Dolce Hotels |
| JI | Jurys Inns |
| LD | Leonardo |
| LJ | Lalit |
| NZ | Ascend |
| IN | Indigo Hotels |
| LC | Luxury Collection |
| LI | LeisureLink Inc |
| OT | Othon Hotels |
| PX | Performance Conn |
| PY | Peabody Hotels |
| SE | Sercotel |
| WF | West Coast Famil |
| ZC | Ritz Club |
| XO | Luxury Resorts |
| AT | Address Hotels |
| CQ | Club Quarters |
| ML | Melrose Hotels |
| DH | Distinguished Hotels |
| PI | Premier Inn |
| ZZ | Independent |
| JT | Jumeirah |
| EZ | Cambria Suites |
| UB | Suburban Extended Stay |
| FB | Fontainebleau |
| GV | Graves Hotels |
| IM | Independent Htls |
| JL | Jumeriah |
| LP | Lexington |
| OP | Omni Partners |
| PV | Preferred Group |
| RJ | Resort Condos |
| RK | Rezlink Intl |
| UV | Univisit |
| VK | Vacationclick |
| VR | Vacation Rentals |
| XN | Global Res |
| XX | New Synxis |
| XZ | Hotelzon |
| OI | Amadeus LinkHotel |
| GF | Grange Hotels |
| EP | Epoque Hotels |
| LO | Langham Hotels |
| PM | Barcelo Hotels |
| QV | ResortQuest Intl |
| XW | WebRes |
| YH | Booking Services |
| YP | Altiuspar Soluti |
| DD | Derag Hotels |
| XR | St Regis |
| 6C | Intercontinental Hotels Group |
| AB | Abba Hotels |
| AE | AmeriHost Inn |
| AV | Allegience Svcs |
| AW | Astra Worldwide |
| BA | Boscolo Hotels |
| BG | Bulgari Hotels |
| BN | Barcelo Hotels |
| BV | Best Value Inns |
| CG | City Lodge Group |
| CN | Conrad |
| CP | Crowne Plaza |
| CU | Charming Hotels |
| CW | Carlson Brands (All) |
| CZ | Comfort Suites |
| DI | Days Inn |
| DM | Domina Hotels |
| DU | Destinations Unl |
| EC | Choice Brands |
| EH | Hilton (All) |
| EK | Sercotel |
| EM | Marriott (All) |
| GI | Hilton Garden Inn |
| GM | Meritus |
| GW | Great Hotels |
| HE | Historic Hotels |
| HF | HomeGate Studios |
| HU | Hyatt Vacation |
| ID | Resnet |
| IF | ACC-NIFOS |
| IS | Ian Schrager |
| IU | Intourist Travel |
| JC | Cendant Brands (All) |
| JU | Jumer |
| KL | ClubHouse Inns |
| LT | Travelodge AU |
| MS | Magnuson Hotels |
| MV | MGM Mirage |
| NN | Louvre Hotels |
| NY | Denihan Hospitality Group |
| OE | Orient Express |
| OK | Alesia |
| OS | Sweden Hotels |
| PK | Park Plaza Intl |
| PT | Prime Hotels |
| RA | Ramada Hotels |
| RN | Expotel |
| RX | Ringhotels |
| SO | Sonesta |
| SV | Sarova Hotels |
| SY | Starhotels |
| TL | Travelodge |
| TV | ReservHotel |
| VC | Marriott Vacation Club |
| WD | Chase Suite Hotels |
| WG | Wingate Inn |
| XS | Summerfield Suites |
| II | Indecorp |
| GZ | Genares Worldwide |
| GE | Gaylord Hotels |
| FV | Flairview |
| EW | Exclusive World |
| GQ | Genre Hotels |
| FX | First Hotel |
| WT | Tryp by Wyndham |
| UN | Carino Hotels |
| GP | Husa Hotels |
| IV | InnVite |
| LG | Lindner Hotels |
| JJ | Jin Jiang Hotels |
| CK | Black Pepper Hotels |
| QO | Swiss Quality Hotels |
| AK | Autograph |
| EB | Edition |
| EQ | Eaton |
| FD | Etours |
| HM | Missoni |
| JG | JG Black Book |
| OO | One And Only |
| UA | Premier Connect |
| PU | Pullman |
| QG | Quest |
| TW | Trump Hotel Collection |
| TF | Thon Hotels |
| IA | Corinthia Hotels |
| NU | Northwood Hospitality |
| HC | hotel.de |
| $$ | Unknown Hotel Vendor |
| QU | Aqua Hotels and Resorts |
| FG | FastBooking |
| BL | Balladins Hotels |
| ZW | CWT Private Hotels |
| DN | Destination |
| XE | Excalibur |
| CY | Courtyard |
| ES | Embassy Suites |
| FN | Fairfield Inns |
| HH | Hilton |
| HI | Holiday Inn |
| HJ | Howard Johnson |
| HY | Hyatt |
| MC | Marriott |
| SI | Sheraton |
| WI | Westin |
| CB | Classic British |
| HT | Home2 Suites |
| JH | Jumer Hotels |
| LQ | La Quinta Inns |
| QR | Quality Htl Res |
| SU | Southern Sun |
| UI | Utell |
| PD | Park Inn |
| SF | Sutton Place Htl |
| YO | Candlewood Stes |
| KG | Knights Inn |
| VG | Villager |
| OZ | Super 8 |
| VY | Maybourne Hotels |
| JD | Doyle Collection |
| EA | Extended Stay |
| VE | Vantis Hotels |
| YX | Synxis Res Svcs |
| BK | Interstate Hotels and Resorts |
| MD | Le Meridien |
| LE | Luxe Worldwide |
| KH | K Hotels |
| FW | Flag Hotels |
| UZ | Unirez |
| GO | Guesthouse International |
| TG | Travelodge UK |
| WO | WorldRes |
| JV | Joie De Vivre |
| PJ | Prince Resorts |
| BI | Best Inns |
| MB | Mandalay Bay |
| YR | Raffles Intl |
| FH | Fiesta Americana |
| NS | NH Hotels |
| NC | Noble House |
| OG | Olympus Hospitality |
| RS | Rockresorts Intl |
| GB | MacDonald Group |
| WB | Relais/Chateaux |
| GG | Grand Hosp. |
| AA | AmericInns |
| MX | Motel 6 |
| DL | Doral Resorts |
| CC | Clarion |
| BT | BT Advantage |
| SA | Sabre Exclusives |
| RV | Red Roof Inns |
| TJ | Taj Hotels |
| BX | Columbus Res Svc |
| BZ | Cmnet Brazil |
| CM | Camino Real |
| DJ | Hotel Port |
| EI | Executive Hotels |
| HK | Hot Key Intl. |
| IH | CIH Hotels |
| KO | KSL Resorts |
| ME | Sol Melia |
| NW | Newtrade |
| PG | Phillips Hotel |
| UE | Universal Resort |
| WS | World Res |
| WV | TravelCLICK |
Ride Vendor Codes
| Vendor Code | Vendor Name |
|---|---|
| $R | RideCharge |
| AL | AddisonLee |
| DG | DeemGroundLimo |
| GC | GroundScope |
| GS | GroundSpan |
| LC | Limoscom |
| SQ | SummitQwest |
| SW | SummitQwest |
| TD | Tandem |
| TV | Transvip |
Semantics Codes
The semantics codes are used in the Charges child elements in Bookings.
| Vendor Type | Semantics Code | Description |
|---|---|---|
| Hotel | OTHER | Other miscellaneous charges |
| Hotel | BUSINESS | Business center charges |
| Hotel | CONFERENCE | Conference charges |
| Hotel | COUNTYTAX | County tax |
| Hotel | VAT | VAT tax |
| Hotel | GST | GST tax |
| Hotel | FEDERALTAX | Federal tax |
| Hotel | FOOD | Food/beverage charges: hotel restaurant, room service |
| Hotel | ALCOHOL | Alcohol charges: beer, wine, and liquor at restaurant |
| Hotel | FOODTAX | Food/beverage taxes |
| Hotel | GIFT | Gift shop charges |
| Hotel | GENERALTAX | General taxes |
| Hotel | HEALTH | Health club, pool, court, golf, etc. |
| Hotel | LAUNDRY | Laundry |
| Hotel | MINIBAR | In room mini-bar |
| Hotel | CITYTAX | City tax |
| Hotel | MOVIE | Movie, in room entertainment |
| Hotel | GAME | Game, in room entertainment |
| Hotel | PARKING | Parking/Valet |
| Hotel | PST | PST tax |
| Hotel | STATETAX | State tax |
| Hotel | PAYMENT | Payment |
| Hotel | DISCOUNT | Discount |
| Hotel | ROOMRATE | Room rate |
| Hotel | ROOMTAX | Room tax |
| Hotel | GRATUITY | Gratutities, tips |
| Hotel | PHONE | Telephone charges |
| Hotel | INTERNET | Internet charges |
| Hotel | NOSHOW | No show fee |
| Hotel | NEGOTIATEDRATE | Negotiated room rate |
| Car | DAYS | DAYS |
| Car | WEEKS | WEEKS |
| Car | MONTHS | MONTHS |
| Car | EXTRAHOURS | EXTRA HOURS |
| Car | EXTRADAYS | EXTRA DAYS |
| Car | EXTRAWEEKS | EXTRA WEEKS |
| Car | MILEAGEFEE | MILEAGE FEE |
| Car | UPGRADEFEE | UPGRADE FEE |
| Car | ADJUSTMENT | ADJUSTMENT |
| Car | DISCOUNT | DISCOUNT |
| Car | COLLECTION | COLLECTION |
| Car | DELIVERY | DELIVERY |
| Car | INTERCITY | INTERCITY |
| Car | ADDLDRIVER | ADDITIONAL DRIVER |
| Car | SERVICECHARGE | SERVICE CHARGE |
| Car | LDWCDW | LDW/CDW |
| Car | ALIAMOUNT | ALI AMOUNT |
| Car | PAIPECAMOUNT | PAI/PEC AMOUNT |
| Car | THEFTPROTECT | THEFT PROTECTION |
| Car | FUELSERVICE | FUEL SERVICE |
| Car | AIRPORTFEE | AIRPORT FEE |
| Car | AGEDIFFER | AGE DIFFERENTIAL |
| Car | CHILDSEAT | CHILD SEAT |
| Car | SKIRACK | SKI RACK |
| Car | ADDLSERVICE | ADDITIONAL SERVICE |
| Car | OTHERCHARGES | OTHER CHARGES |
| Car | TRANSACTIONFEE | TRANSACTION FEE |
| Car | SATELLITERADIO | SATELLITE RADIO |
| Car | NEVERLOST | NEVERLOST |
| Car | ACSURCHARGE | A/C SURCHARGE |
| Car | RESERVATIONFEE | RESERVATION FEE |
| Car | TAXDIFFER | TAX DIFFERENTIAL |
| Car | VOUCHERADJUST | VOUCHER ADJUSTMENT |
| Car | VATAMOUNT | VAT AMOUNT |
| Car | GSTAMOUNT | GST AMOUNT |
| Car | VEHICLELICENSE | VEHICLE LICENSE FEE |
| Car | CUSTFACILITY | CUSTOMER FACILITY |
| Car | VEHLEASETAX | MOTOR VEHICLE LEASE TAX |
| Car | ROADTAX | ROAD TAX |
| Car | OTHER | OTHER |
| Car | ACRECOVERYFEE | AIR CONDITION RECOVERY FEE |
| Car | CONCESSIONFEE | CONCESSION PASS THRU FEE |
| Car | CUSTRELATIONS | CUSTOMER RELATIONS EXPENSE |
| Car | TFFCORPVRT | TFFC OR PVRT |
| Car | IMPOUNDSTORAGE | IMPOUND/STORAGE |
| Car | LISAMOUNT | LIS AMOUNT |
| Car | SUPLIABILITY | SUPPLEMENTAL LIABILITY PROTECTION |
| Car | DROPOFFFEE | DROPOFF FEE |
| Car | WEEKEND | WEEKEND DAILY RATE |
| Air | OTHER | Miscellaneous charge |
| Air | SEGFEE | Segment fee |
| Air | SEGFEE_AS_FEE | Segment fees as fee |
| Air | SEGFEE_AS_FARE | Segment fees as base fare |
| Air | SEGFEE_AS_TAX | Segment fee as tax |
| Air | WIRELESS_FEE | Wireless Fee |
| Rail | OTHER | Miscellaneous charge |
| Rail | TICKET | Price of ticket |
| Rail | SEAT | Price of seat |
Time Zones
SAP Concur converts local date/time to UTC. In order to do that we need to be able to determine where the local time is.
Olson Time Zones
- Best practice is providing TimeZone (Olson or Windows time zone format) in addition to the required StartDateLocal and EndDateLocal.
- If you cannot provide TimeZone (Olson or Windows time zone format), SAP Concur recommends StartDateUtc and EndDateUtc in addition to the required StartDateLocal and EndDateLocal.
- Least preferable is providing StartCityCode in addition to the required StartDateLocal and EndDateLocal, if you cannot provide TimeZone or StartDateUtc and EndDateUtc.
| Africa/Cairo | Africa/Casablanca | Africa/Harare | Africa/Luanda |
| Africa/Nairobi | Africa/Windhoek | America/Anchorage | America/Argentina/Buenos_Aires |
| America/Asuncion | America/Bahia | America/Bogota | America/Buenos_Aires |
| America/Caracas | America/Chicago | America/Chihuahua | America/Denver |
| America/Godthab | America/Guyana | America/Halifax | America/Indianapolis |
| America/Los_Angeles | America/Manaus | America/Mexico_City | America/Montevideo |
| America/New_York | America/Phoenix | America/Regina | America/Santiago |
| America/Sao_Paulo | America/St_Johns | America/Swift_Current | America/Tijuana |
| Asia/Almaty | Asia/Amman | Asia/Baghdad | Asia/Baku |
| Asia/Bangkok | Asia/Beirut | Asia/Calcutta | Asia/Colombo |
| Asia/Damascus | Asia/Dhaka | Asia/Irkutsk | Asia/Jerusalem |
| Asia/Kabul | Asia/Kamchatka | Asia/Karachi | Asia/Karachi |
| Asia/Katmandu | Asia/Krasnoyarsk | Asia/Magadan | Asia/Muscat |
| Asia/Novosibirsk | Asia/Rangoon | Asia/Riyadh | Asia/Seoul |
| Asia/Shanghai | Asia/Singapore | Asia/Taipei | Asia/Tbilisi |
| Asia/Tehran | Asia/Tokyo | Asia/Ulaanbaatar | Asia/Vladivostok |
| Asia/Yakutsk | Asia/Yekaterinburg | Asia/Yerevan | Atlantic/Azores |
| Atlantic/Cape_Verde | Atlantic/South_Georgia | Australia/Adelaide | Australia/Brisbane |
| Australia/Darwin | Australia/Hobart | Australia/Perth | Australia/Sydney |
| Etc/GMT+12 | Etc/GMT-11 | Etc/GMT-2 | Europe/Athens |
| Europe/Berlin | Europe/Helsinki | Europe/Istanbul | Europe/Kaliningrad |
| Europe/London | Europe/Minsk | Europe/Moscow | Europe/Paris |
| Europe/Prague | Europe/Sarajevo | GMT | GMT-1200 |
| Indian/Mauritius | Pacific/Apia | Pacific/Auckland | Pacific/Fiji |
| Pacific/Guadalcanal | Pacific/Guam | Pacific/Honolulu | Pacific/Tongatapu |
| UTC |
Windows Time Zones
| Africa/Cairo | Africa/Casablanca | Africa/Harare | Africa/Luanda |
| Africa/Nairobi | Africa/Windhoek | America/Anchorage | America/Argentina/Buenos_Aires |
| America/Asuncion | America/Bahia | America/Bogota | America/Buenos_Aires |
| America/Caracas | America/Chicago | America/Chihuahua | America/Denver |
| America/Godthab | America/Guyana | America/Halifax | America/Indianapolis |
| America/Los_Angeles | America/Manaus | America/Mexico_City | America/Montevideo |
| America/New_York | America/Phoenix | America/Regina | America/Santiago |
| America/Sao_Paulo | America/St_Johns | America/Swift_Current | America/Tijuana |
| Asia/Almaty | Asia/Amman | Asia/Baghdad | Asia/Baku |
| Asia/Bangkok | Asia/Beirut | Asia/Calcutta | Asia/Colombo |
| Asia/Damascus | Asia/Dhaka | Asia/Irkutsk | Asia/Jerusalem |
| Asia/Kabul | Asia/Kamchatka | Asia/Karachi | Asia/Karachi |
| Asia/Katmandu | Asia/Krasnoyarsk | Asia/Magadan | Asia/Muscat |
| Asia/Novosibirsk | Asia/Rangoon | Asia/Riyadh | Asia/Seoul |
| Asia/Shanghai | Asia/Singapore | Asia/Taipei | Asia/Tbilisi |
| Asia/Tehran | Asia/Tokyo | Asia/Ulaanbaatar | Asia/Vladivostok |
| Asia/Yakutsk | Asia/Yekaterinburg | Asia/Yerevan | Atlantic/Azores |
| Atlantic/Cape_Verde | Atlantic/South_Georgia | Australia/Adelaide | Australia/Brisbane |
| Australia/Darwin | Australia/Hobart | Australia/Perth | Australia/Sydney |
| Etc/GMT+12 | Etc/GMT-11 | Etc/GMT-2 | Europe/Athens |
| Europe/Berlin | Europe/Helsinki | Europe/Istanbul | Europe/Kaliningrad |
| Europe/London | Europe/Minsk | Europe/Moscow | Europe/Paris |
| Europe/Prague | Europe/Sarajevo | GMT | GMT-1200 |
| Indian/Mauritius | Pacific/Apia | Pacific/Auckland | Pacific/Fiji |
| Pacific/Guadalcanal | Pacific/Guam | Pacific/Honolulu | Pacific/Tongatapu |
| UTC |
Itinierary API Usage
Itinerary Web Service (TMC/Third-Party)
The SAP Concur Itinerary Web Service allows Travel Management Companies (TMC), SAP Concur clients, and third-party developers to view and create travel related events in the Concur Travel system. TMCs can post bookings for any travel type. This web service can also be used by SAP Concur clients and third-party developers to request trip information for SAP Concur users. The public Itinerary XSD can be found here. In addition, the GetList XSD can be found here.
- GET List of Itineraries
- GET Itinerary Details
- POST Itinerary Details
- POST Itinerary Cancellation
- POST Booking Details
- POST Booking Cancellation
- Booking Object Elements
GET List of Itineraries
Retrieves trip summaries for the traveler specified in the OAuth token. This endpoint can also be used to get details for trips for a different user or the whole company. This is most often done when a Travel Management Company needs to get a list of trips on behalf of a user or company. During the request, a user with one of the following user roles from the user's company must authenticate through OAuth: Web Services Administrator for Professional, or Can Administer for Standard.
The response for this function can be divided into pages for easier processing.
Parameters
| Name | Description |
|---|---|
tripId |
The trip id |
startDate={_date_} |
The URL-encoded start date (in Coordinated Universal Time, aka UTC) for the trip. Format: YYYY-MM-DD. If no query parameters are provided, the start date is set to today's date - 30 days. The request will only return trips that are ongoing during the provided dates, either starting on the date, or starting before the date and ongoing during the provided date. |
endDate****={_date_} |
The URL-encoded UTC end date for the trip. Format: YYYY-MM-DD. If no query parameters are provided, the end date is set to today's date + 12 months. The request will only return trips that are ongoing during the provided dates, either ending on the date, or starting before the date and ongoing during the provided date. |
createdAfterDate****={_date_} |
The URL-encoded UTC date for when the trip was created. The query string will return trips created on or after this date. Used with the createdBeforeDate for finding trips created during a date range. Format: YYYY-MM-DD. |
createdBeforeDate****={_date_} |
The URL-encoded UTC date for when the trip was created. The query string will return trips created on or before this date. Used with the createdAfterDate for finding trips created during a date range. Format: YYYY-MM-DD. |
lastModifiedDate****={_date_} |
The last modified UTC date of the trips and any their associated bookings. This query string will return only the trips where the trip or any of its associated bookings have a last modified date that is greater or equal to the supplied time. The provided date/time can be anytime between now and the first date of trip creation in the database. The format is either the date or the date and time combined. |
bookingType={_type_} |
The trip includes at least one booking of this type. Format: Air, Car, Dining, Hotel, Parking, Rail, or Ride |
userid_type=login&userid_value=_{loginID}_ |
The loginID is the user's SAP Concur login ID. The userid_value of ALL can be sent to get trip summaries for all users at the company. The userid_type and userid_value parameters can only be used if the OAuth consumer has one of the user roles listed above. |
includeMetadata=true&ItemsPerPage={_number_}&Page={_number_} |
The includeMetadata query parameter combined with the ItemsPerPage and Page query parameters will cause the response to be divided into pages. The response will be wrapped in a ConcurResponse parent element, with both the response details and the paging metadata included. The details of the response are here. If the ItemsPerPage query parameter is not sent, the response will default to 200 if the Page query parameter is sent, or 1000 if the Page query parameter is not set. If the Page query parameter is not sent, the response will default to page 1. |
includeVirtualTrip=_1_ |
Virtual trips are segments booked offline through the Travel Request product. Set the includeVirtualTrip query parameter to 1 to include those trips in the list. |
includeCanceledTrips=_{true/false}_ |
The includeCanceledTrips query parameter will cause the request to also return trips with a status of Canceled. When this query parameter is set to true, the response will include the TripStatus element. |
Examples:
To get itinerary list for the entire company (OAuth consumer must have Admin user role):
https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={startdate}&endDate={enddate}&_createdAfterDate={_date}&createdBeforeDate={date}&lastModifiedDate={date}&bookingType={type}&userid_type=login&userid_value=ALL
To get itinerary list for a single user (the OAuth consumer):
https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={startdate}&endDate={enddate}&_createdAfterDate={_date}&createdBeforeDate={date}&lastModifiedDate={date}&bookingType={type}
To get itinerary list for a single user (other than the OAuth consumer):
https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={startdate}&endDate={enddate}&_createdAfterDate={_date}&createdBeforeDate={date}&lastModifiedDate={date}&bookingType={type}&userid_type=login_id&userid_value={loginID}
XML Example Request by Start and End Date
GET /api/travel/trip/v1.1/?startDate=2012%2F02%2F01&endDate=2013%2F12%2F31 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...
XML Example Request by Booking Type and Start Date
GET /api/travel/trip/v1.1/?startDate=2012%2F02%2F01&bookingType=Air HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...
XML Example Request by Created Date
GET /api/travel/trip/v1.1/?createdAfterDate=2012%2F02%2F01 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
XML Example Request with Paging
GET /api/travel/trip/v1.1/?createdAfterDate=2012%2F02%2F01&includeMetadata=true&ItemsPerPage=2&Page=1 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Get List of Itineraries Response
This request will return an ItineraryInfoList parent element with an ItineraryInfo child element for each trip summary for the specified traveler. Each ItineraryInfo element has the following child elements:
| Name | Description |
|---|---|
TripId |
Encrypted trip identifier value. |
TripName |
Name of the trip |
TripStatus |
The status of the trip. This element only appears if the includeCanceledTrips query parameter is used in the request. |
StartDateLocal |
The start date of the trip in the starting location's timezone. Format: YYYY-MM-DDThh:mm:ss. |
EndDateLocal |
The end date of the trip in the ending location's timezone. Format: YYYY-MM-DDThh:mm:ss. |
UserLoginId |
The user's login to SAP Concur. Only appears when the OAuth consumer has one of the specified admin roles. |
DateModifiedUtc |
The UTC date that this trip was last modified. Format: YYYY-MM-DDThh:mm:ss. |
id |
Trip ID URI with encrypted ID. |
Paging
If the includeMetadata and ItemsPerPage query parameters are included in the request, the response will include a ConnectResponse parent element with the following elements:
| Name | Description |
|---|---|
Data |
This parent element contains the response as detailed above. |
Metadata |
This parent element contains the Paging elements. |
Paging Elements
The parent element of the paging information. Contains the following child elements:
| Name | Description |
|---|---|
TotalPages |
The total number of pages the query returned. |
TotalItems |
The total number of itineraries the query returned. |
CurrentPage |
The page number for the set of results in the current response. |
ItemsPerPage |
The number of items set to display per page. |
PreviousPageURL |
The URI to the previous page of results. This element will be empty when there are no previous pages. |
NextPageURL |
The URI to the next set of results. This element will be empty when there are no next pages. |
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
...
<?xml version="1.0" encoding="utf-8"?>
<ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ItineraryInfo>
<TripId>naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</TripId>
<TripName>Trip from Baltimore to New York</TripName>
<StartDateLocal>2012-02-15T09:00:00</StartDateLocal>
<EndDateLocal>2012-02-21T17:30:00</EndDateLocal>
<UserLoginId>cm@example.com</UserLoginId>
<DateModifiedUtc>2012-02-14T17:13:07</DateModifiedUtc>
<id>https://www.concursolutions.com/api/travel/trip/v1.1/naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</id>
</ItineraryInfo>
<ItineraryInfo>
<TripId>I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</TripId>
<TripName>Trip from Baltimore to Seattle</TripName>
<StartDateLocal>2012-03-26T09:00:00</StartDateLocal>
<EndDateLocal>2012-03-29T17:30:00</EndDateLocal>
<DateModifiedUtc>2012-03-24T19:00:00</DateModifiedUtc>
<UserLoginId>cm@example.com</UserLoginId>
<id>https://www.concursolutions.com/api/travel/trip/v1.1/I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</id>
</ItineraryInfo>
</ItineraryInfoList>
XML Example of Successful Response with Paging
HTTP/1.1 200 OK
Content-Type: application/xml
...
<ConnectResponse>
<Metadata>
<Paging>
<TotalPages>38</TotalPages>
<TotalItems>187</TotalItems>
<CurrentPage>2</CurrentPage>
<ItemsPerPage>2</ItemsPerPage>
<PreviousPageURL>https://www.concursolutions.com/api/travel/trip/v1.1/?createdAfterDate=2012%2F02%2F01&itemsPerPage=5&page=3&includeMetaData=true</PreviousPageURL>
<NextPageURL>https://www.concursolutions.com/api/travel/trip/v1.1/?createdAfterDate=2012%2F02%2F01&itemsPerPage=5&page=1&includeMetaData=true</NextPageURL>
</Paging>
</Metadata>
<Data>
<ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ItineraryInfo>
<TripId>naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</TripId>
<TripName>Trip from Baltimore to New York</TripName>
<StartDateLocal>2012-02-15T09:00:00</StartDateLocal>
<EndDateLocal>2012-02-21T17:30:00</EndDateLocal>
<UserLoginId>cm@example.com</UserLoginId>
<DateModifiedUtc>2012-02-14T17:13:07</DateModifiedUtc>
<id>https://www.concursolutions.com/api/travel/trip/v1.1/naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</id>
</ItineraryInfo>
<ItineraryInfo>
<TripId>I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</TripId>
<TripName>Trip from Baltimore to Seattle</TripName>
<StartDateLocal>2012-03-26T09:00:00</StartDateLocal>
<EndDateLocal>2012-03-29T17:30:00</EndDateLocal>
<DateModifiedUtc>2012-03-24T19:00:00</DateModifiedUtc>
<UserLoginId>cm@example.com</UserLoginId>
<id>https://www.concursolutions.com/api/travel/trip/v1.1/I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</id>
</ItineraryInfo>
</ItineraryInfoList>
</Data>
</ConnectResponse>
GET Itinerary Details
Retrieves the details for the specified trip. By default, the OAuth consumer should be the owner of the trip. This endpoint can also be used to get details for trips that the OAuth consumer does not own. This is most often done when a Travel Management Company needs to get trip details on behalf of a user. The TMC must be registered with SAP Concur and have a SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
The returned elements will vary based on the following conditions:
- Some elements, such as AirlineTickets or RailPayments, will only appear for bookings of the appropriate type.
- Amount values, such as Rate or Tax, will only appear if the requestor is the source of the booking. All other suppliers will not receive the amount elements associated with the bookings.
- Some elements, such as SabreDKNumber, will only appear if the booking was created by the relevant GDS.
- Some elements are vendor-specific and will only appear in responses for the associated vendor.
This documentation contains the full set of possible elements that can be returned. No itinerary can contain all of the possible elements, so the response will always be a subset of the possible returned values.
Parameters
| Name | Description |
|---|---|
{_tripId_} |
Required. The identifier for the desired trip. |
userid_type=login&userid_value=_{loginID}_ |
The loginID is the user's SAP Concur login ID. The userid_value of ALL can be sent to get trip summaries for all users at the company. The userid_type and userid_value parameters can only be used if the OAuth consumer has one of the user roles listed above. |
systemFormat=_{format}_ |
The systemFormat query parameter can be used to specify that the response is formatted for a different system. The supported value is Tripit. |
Get Itinerary Details Response
This request will return an Itinerary parent element with a subset of the following child elements:
Parameters
| Name | Description |
|---|---|
BookedByFirstName |
The first name of the person who booked the trip. |
BookedByLastName |
The last name of the person who booked the trip. |
BookedVia |
The booking method for the trip. |
CancelComments |
The comments provided if the itinerary is cancelled. Maximum length: 256 characters. |
Comments |
Optional comments. Maximum length: 512 characters. |
DateBookedLocal |
The date the trip was booked, in the local time of the booking location. Format: YYYY-MM-DDThh:mm:ss |
DateCreatedUtc |
The date that this trip was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
DateModifiedUtc |
The date that this trip was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
Description |
The trip description. Maximum length: 512 characters. |
EndDateLocal |
The end date of the trip in the ending location's timezone. Format: YYYY-MM-DDThh:mm:ss |
EndDateUtc |
The end date of the trip, in UTC. Format: YYYY-MM-DDThh:mm:ss |
IsPersonal |
Whether the trip is a Business or Leisure trip. Format: true/false. |
ProjectName |
The associated project name for the trip. Maximum length: 255 characters. |
StartDateLocal |
The start date of the trip in the starting location's timezone. Format: YYYY-MM-DDThh:mm:ss |
StartDateUtc |
The start date of the trip, in UTC. Format: YYYY-MM-DDThh:mm:ss |
TripName |
Name of the trip. Maximum length: 255 characters. |
Bookings |
This parent element will contain a Booking child element for each booking associated with this itinerary. Refer to the Booking Child Elements table. |
RuleViolations |
The list of rule violations associated with the itinerary. This parent element contains a RuleViolation child element for each associated rule violation. Refer to the Public Itinerary XSD for more information. |
Status |
The status of the itinerary. One of the following: 0 = Confirmed; 1 = Ticketed by agent; 2 = Canceled |
Booking Child Elements
| Name | Description |
|---|---|
BookingSource |
The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place. |
DateBookedLocal |
The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
DateCreatedUtc |
The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
DateModifiedUtc |
The date the booking was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
FormOfPaymentName |
The name of the form of payment for the booking. |
FormOfPaymentType |
The type of the form of payment. |
PassengerCount |
The number of passengers included in the booking. |
RecordLocator |
Record locator for this booking. This is often six alphanumeric characters but can have other formats depending on the booking source. |
RetrievedDateUtc |
The date the booking was last accessed, in UTC. Format: YYYY-MM-DDThh:mm:ss |
TicketMailingAddress |
The mailing address for the booked ticket, if any. |
TicketPickupLocation |
The pickup location for the booked ticket, if any. |
TicketPickupNumber |
The confirmation number to pick up the booked ticket, if any. |
AirfareQuotes |
List of stored airfare quotes. This parent element has a Quote child element for each airfare quote. The Quote parent element contains Airfare Quotes Child Elements |
AirlineTickets |
List of Airline Tickets. This parent element contains Airline Tickets Child Elements |
Charges |
The charges for the booking. |
MiscChargeOrders |
This parent element has a MiscellaneousChargeOrder child element for each included miscellaneous charge. The MiscellaneousChargeOrder parent element contains Miscellaneous Charge Order Child Elements |
Passengers |
This parent element has a Passenger child element for each included passenger. Refer to the Passenger Child Elements |
PassPrograms |
This parent element has Pass Program child elements for each pass program associated with the booking. |
PhoneNumbers |
This parent element has Phone Number Data child elements for each phone number associated with the booking. |
RailPayments |
This parent element has Rail Payment Child Elements |
Segments |
This parent element will contain at least one of the following child elements: Air, Car, Hotel, Dining, Ride, Rail, Parking. |
Delivery |
The method used to deliver this booking. Refer to the Delivery Method Child Elements |
WaitListSegments |
Information will appear in this element if the segment is on a waiting list. |
Warnings |
The warnings associated with the booking. |
WebAddresses |
List of web addresses. This parent element includes Web Address Data child elements for each associated web address. |
BookingReferrer |
BookingReferrer is used only in specific source tracking scenarios when there is a need to distinguish between bookings with the same BookingSources coming through different flows. Do not populate without coordinating with your technical contact. The supported values are: Concur Travel, Sign-in with SAP Concur, Supplier Mobile, Supplier Web. |
Airfare Quotes Child Elements
| Name | Description |
|---|---|
BaseFare |
The base fare of the booking quote. |
BaseFareCurrency |
The 3-letter ISO 4217 currency code for the booking quote. |
BaseFareNuc |
The base fare in NUC. |
BaseFareNucCurrency |
The 3-letter ISO 4217 currency code for the base fare in NUC. |
DateCreatedUtc |
The date the quote was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
DateModifiedUtc |
The date the quote was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
Endorsements |
Notes from the airline if it endorses the ticket as acceptable on a different airline. |
IssueByDate |
The date the quote must be issued by. Format: YYYY-MM-DDThh:mm:ss |
TotalFare |
The total price of the booking. |
TotalFareCurrency |
The 3-letter ISO 4217 currency code for the total fare. |
AirlineCharges |
The charges applied by the airline. This parent element contains a Fixed child element for each fixed charge from the airline. |
Taxes |
The taxed applied to this airline ticket. |
Airline Tickets Child Elements
| Name | Description |
|---|---|
ManualAirlineTicket |
The manual airline ticket for the booking. |
AirlineTicket |
The airline ticket for the booking. |
AirlineAdjustment |
Any adjustment made to the booking. |
Miscellaneous Charge Order Child Elements
| Name | Description |
|---|---|
DateCreatedUtc |
The date the charge order was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
DateModifiedUtc |
The date the charge order was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
IssueDate |
The date the charge order was issued. Format: YYYY-MM-DDThh:mm:ss |
PlatingCarrierNumericCode |
Part of the ticket number that indicates the airline code. This is a three digit number. For example: 001=American, 005=Continental, 006=Delta, 012=Northwest |
PlatingControlNumber |
Part of the ticket number that indicates the ticket control number. Format: Ten digit number. |
TotalAmount |
The total amount of charge orders for the ticket. |
TotalAmountCurrency |
The 3-letter ISO 4217 currency code for the total charge order amount. |
Pass Programs Child Elements
| Name | Description |
|---|---|
Amount |
The program amount. |
Name |
The program name. |
Type |
The program type. |
UserFirstName |
The first name of the passenger. |
UserLastName |
The last name of the passenger. |
Phone Number Data Child Elements
| Name | Description |
|---|---|
PassengerRPH |
Indicates the passenger to whom this phone number belongs. |
PhoneNumber |
The passenger's phone number. |
Type |
The type of phone number. |
Description |
The description for the phone number. |
Rail Payments Child Elements
| Name | Description |
|---|---|
RailPayment |
The payment information for a rail booking. |
RailAdjustment |
The amount adjusted for a rail booking. Refer to the Public Itinerary XSD for more information. |
Delivery Method Child Elements
| Name | Description |
|---|---|
LocationAdditionalDetails |
Additional information about the delivery location. |
AddressLine1 |
The delivery address. |
AddressLine2 |
The delivery address. |
City |
The delivery address. |
Country |
The delivery address. |
LocationDesc |
Description of the delivery location. |
Email |
The delivery email contact. |
Latitude |
The delivery address. |
Longitude |
The delivery address. |
LocationName |
The name of the delivery location. |
PhoneNumber |
The phone number of the delivery contact. |
ReferenceNumber |
The reference number for the delivery. |
State |
The delivery address. |
Type |
The type of delivery address. |
Zip |
The delivery address. |
Web Address Data Child Elements
| Name | Description |
|---|---|
PassengerRPH |
Indicates the passenger to whom this web address belongs. |
WebAddress |
Web address. Format: email address or URL. Maximum length: 250 characters. |
Format |
Format of the web address. Format: E=Email, U=URL, I=IM |
Type |
Type code for web address. Format: TKT, RES, BUS |
Description |
Free text describing the web address. Maximum length: 50 characters. |
Passenger Child Elements
| Name | Description |
|---|---|
FirstNameNumber |
The number of characters in the passenger's first name. |
LastNameNumber |
The number of characters in the passenger's last name. |
NameFirst |
The passenger's first name. |
NameLast |
The passenger's last name. |
NameMiddle |
The passenger's middle name. |
NamePrefix |
The passenger's name prefix. |
NameRemark |
Additional details about the passenger's name. |
NameSuffix |
The passenger's name suffix. |
NameTitle |
The passenger's name title. |
TextName |
The user's full name. |
FrequentTravelerProgram |
The passenger's loyalty program identifier. This parent element contains the FrequentFlyer and RailProgram child elements. |
FrequentFlyer |
The passenger's frequent flyer program details. This parent element has Frequent Flyer Child Elements |
RailProgram |
The passenger's rail loyalty program details. This parent element has Rail Program Child Elements |
Frequent Flyer Child Elements
| Name | Description |
|---|---|
AirlineVendor |
The vendor of the frequent flyer program. |
Description |
The program description. |
DiscountProgramExpirationDate |
The date the discount program enrollment expires. Format: YYYY-MM-DDThh:mm:ss |
DiscountProgramType |
The type of discount program. |
FrequentFlyerNumber |
The passenger's identifier for the program. |
ProgramVendor |
The program vendor. |
Status |
The passenger's program status. |
StatusExpirationDate |
The expiration date for the passenger's program status. |
Rail Program Child Elements
| Name | Description |
|---|---|
Description |
Description of the discount program. |
DiscountProgramExpirationDate |
The date the discount program enrollment expires. Format: YYYY-MM-DDThh:mm:ss |
DiscountProgramType |
The type of discount program. |
ProgramNumber |
The passenger's identifier for the program. |
ProgramVendor |
The program vendor. |
Status |
The passenger's program status. |
StatusExpirationDate |
The expiration date for the passenger's program status. |
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
...
<?xml version="1.0" encoding="utf-8"?>
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
<ItinLocator>CNQR1234567890</ItinLocator>
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<TripName>Trip from Dallas to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<BookedVia>EveryGDS</BookedVia>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
<Bookings>
<Booking>
<Segments>
<Car>
<Vendor>CQ</Vendor>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<ConfirmationNumber>F1672664579</ConfirmationNumber>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>M</Transmission>
<AirCondition>R</AirCondition>
<NumCars>1</NumCars>
<DiscountCode>346660</DiscountCode>
<DailyRate>44.0000</DailyRate>
<TotalRate>44.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
<Charges>
<Fixed>
<Description>Dropoff Fee</Description>
<Currency>USD</Currency>
<Amount>0.0000</Amount>
<IsPrimary>false</IsPrimary>
<SemanticsCode>DROPOFFFEE</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
</Fixed>
<RateWithAllowance>
<Currency>USD</Currency>
<Amount>44.0000</Amount>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<IsPrimary>true</IsPrimary>
<SemanticsCode>DAYS</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>1.0000</NumUnits>
<AllowanceNumUnits>250.0000</AllowanceNumUnits>
<AllowanceAmount>0.2400</AllowanceAmount>
<AllowanceIsUnlimited>false</AllowanceIsUnlimited>
</RateWithAllowance>
</Charges>
</Car>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>ConcurCars</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>TravelSupplier</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
<Booking>
<Segments>
<Hotel>
<Vendor>CQ</Vendor>
<Status>GK</Status>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<ConfirmationNumber>3364214265</ConfirmationNumber>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<RateCode>LV4</RateCode>
<Name>CONCUR HOTEL</Name>
<HotelPropertyId>CONQ</HotelPropertyId>
<CheckinTime>00:00</CheckinTime>
<CheckoutTime>00:00</CheckoutTime>
<NumPersons>1</NumPersons>
<NumRooms>1</NumRooms>
<CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
<DailyRate>240.3500</DailyRate>
<Currency>USD</Currency>
<RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
<Charges>
<Rate>
<Currency>USD</Currency>
<Amount>240.3500</Amount>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<IsPrimary>false</IsPrimary>
<SemanticsCode>ROOMRATE</SemanticsCode>
<SemanticsVendorType>H</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>3.0000</NumUnits>
</Rate>
</Charges>
</Hotel>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>ConcurHotel</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<OriginalItinLocator>33491211</OriginalItinLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
</Bookings>
</Itinerary>
XML Response in TripIt Format
<?xml version="1.0" encoding="utf-8"?>
<Response>
<Trip>
<id>73014481752</id>
<relative_url>/api/travel/trip/v1.1/73014481752</relative_url>
<start_date>2013-08-21</start_date>
<end_date>2013-08-24</end_date>
<display_name>Strategy Team meeting</display_name>
<is_private>true</is_private>
</Trip>
<AirObject>
<booking_site_conf_num>RL10001005</booking_site_conf_num>
<booking_site_name>Concur Travel</booking_site_name>
<booking_site_phone></booking_site_phone>
<booking_site_url>https://www.concursolutions.com</booking_site_url>
<record_locator>4294993825</record_locator>
<supplier_conf_num>CN10001005</supplier_conf_num>
<supplier_contact></supplier_contact>
<supplier_email_address></supplier_email_address>
<supplier_name></supplier_name>
<supplier_phone></supplier_phone>
<supplier_url></supplier_url>
<is_purchased>1</is_purchased>
<notes></notes>
<restrictions></restrictions>
<total_cost></total_cost>
<Segment>
<StartDateTime>
<date>2013-08-21</date>
<time>07:45:00</time>
</StartDateTime>
<EndDateTime>
<date>2013-08-21</date>
<time>13:03:00</time>
</EndDateTime>
<start_airport_code>PHX</start_airport_code>
<start_gate>A11</start_gate>
<start_terminal>4</start_terminal>
<end_airport_code>ORD</end_airport_code>
<end_gate>F8</end_gate>
<end_terminal>2</end_terminal>
<marketing_airline>US</marketing_airline>
<marketing_flight_number>1</marketing_flight_number>
<aircraft>320</aircraft>
<duration></duration>
<distance>1433</distance>
<notes></notes>
<seats></seats>
<service_class>Economy</service_class>
<stops>Nonstop</stops>
</Segment>
<Segment>
<StartDateTime>
<date>2013-08-24</date>
<time>13:55:00</time>
</StartDateTime>
<EndDateTime>
<date>2013-08-24</date>
<time>16:58:00</time>
</EndDateTime>
<start_airport_code>ORD</start_airport_code>
<start_gate></start_gate>
<start_terminal></start_terminal>
<end_airport_code>PHX</end_airport_code>
<end_gate></end_gate>
<end_terminal></end_terminal>
<marketing_airline>US</marketing_airline>
<marketing_flight_number>1728</marketing_flight_number>
<aircraft>A320</aircraft>
<duration></duration>
<distance></distance>
<notes></notes>
<seats></seats>
<service_class>Economy</service_class>
<stops> stops</stops>
</Segment>
<Traveler>
<first_name>William</first_name>
<middle_name></middle_name>
<last_name>Never</last_name>
<frequent_traveler_num></frequent_traveler_num>
<frequent_traveler_supplier></frequent_traveler_supplier>
<ticket_num></ticket_num>
</Traveler>
</AirObject>
</Response>
POST Itinerary Details
Description
Creates a new trip or updates an existing trip. A new trip will be created if the trip dates span no existing trip and the request doesn't include a tripId. If a tripId is included in the URI it will update the specified trip. The full trip information is included in the update request, which replaces the existing trip.
This endpoint can be used to create trips for a user that is not the OAuth consumer. This is most often done when a travel supplier or Travel Management Company needs to create a trip on behalf of a user. The supplier or TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
Agency Proposals
Travel Management Companies for SAP Concur clients with the Agency Proposal feature of Travel Request can send proposed itineraries using the Itinerary web service. The TMC will indicate that the itinerary is a proposal using the TripStatus element. The request must also include the CustomAttributes element and its child elements.
| Query Parameters - Required | Supported Content Types |
|---|---|
| None | application/xml |
Query Parameters - Optional
- {tripId}
The identifier for the desired trip. Provided if the request is updating an existing trip. - userid_type=login_id&userid_value={loginID}
The SAP Concur loginID of the user that owns the trip. Can be used when creating a new trip or updating an existing trip. The userid_type and userid_value parameters can only be used if the OAuth consumer has the user role listed above.
Examples:
To post a new trip for the OAuth consumer:
https://www.concursolutions.com/api/travel/trip/v1.1
To update a trip for the OAuth consumer:
https://www.concursolutions.com/api/travel/trip/v1.1?tripId={_tripId_}
To post a trip for a user other than the OAuth consumer:
https://www.concursolutions.com/api/travel/trip/v1.1?userid_type=login_id&userid_value={_loginID_}
| Request Headers - Required | Request Headers - Optional |
|---|---|
| Authorization header with OAuth token for valid SAP Concur user. To post trips for users other than the OAuth consumer, the OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. | None |
Content Body
This function requires as its arguments an Itinerary parent element. The parent element contains the following child elements:
Required Elements
| Element | Description |
|---|---|
| TripName | Name of the trip. Maximum length: 255 characters. |
| TripStatus | The status of the itinerary. One of the following: 0 - Confirmed 1 - Ticketed 2 - Canceled 6 - Proposal 7 - Booked Proposal |
Required Elements for Agency Proposal
| Element | Description |
|---|---|
| ClientLocator | The unique identifier for the batch of proposals. All proposals in the batch should have the same value. |
| TravelRequestId | The identifier for the travel request that the proposal is associated with. |
| CustomAttributes | This parent element will contain CustomAttributes child element. The CustomAttributes child elements are detailed in the CustomAttributes Elements table. |
CustomAttributes Elements - Required
| DataType | Name | Data Supported Values | Comment |
|---|---|---|---|
| Numeric | ProposalBatchSize | 1 to 3 | The number of proposals in the batch. Maximum: 3 |
| Numeric | ProposalSequenceIndex | 1 to 3 | The index of the proposal in the batch of proposals. |
| Text | AutoSelectProposal | True, False | If true, then the proposal will be selected accordingly and replace the segments previously entered by the user. If False, then the proposal will be up to the user to decide which proposal s/he wants to manually select. |
| Text | TicketIssued | True, False | Are the tickets for this proposal issued or not. |
| Text | DisplayOnItinerary | True | The value for this element has to be 'True'. |
| N/A | DisplayTitle | N/A | This element should be empty. |
| N/A | ExternalId | N/A | This element should be empty. |
Optional Elements
| Element | Description |
|---|---|
| BookedByFirstName | First name of the trip owner. |
| BookedByLastName | Last name of the trip owner. |
| Bookings | This parent element will contain a Booking child element for each booking associated with this itinerary. The Booking child elements are detailed in the Booking Elements table. |
| CancelComments | User supplied comments if the trip is cancelled. 256 Characters Maximum |
| Comments | Comments on the itinerary. 512 Characters Maximum |
| DateBookedLocal | The date the trip was booked, in the local time of the booking location. Format: YYYY-MM-DDThh:mm:ss |
| Description | The trip description. Maximum length: 512 characters. |
| IsPersonal | Whether the trip is a Business or Leisure trip. |
| ProjectName | The associated project name for the trip. Maximum length: 255 characters. |
| RuleViolations | The list of rule violations associated with the itinerary. This parent element contains a |
Booking Elements - Required
| Element | Description |
|---|---|
| BookingSource | The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place. This could be a GDS, OTA, Vendor code for Supplier website, or Supplier Direct Connect API. |
| RecordLocator | The unique identifier for the booking. Send the value for an existing booking to update an existing trip. |
Booking Elements - Optional
| Element | Description |
|---|---|
| BookingOwner | Indicates the tool that supplied the booking to Concur Travel. |
| Source | Obsolete, supported for backward compatibility. |
| DateBookedLocal | The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| FormOfPaymentName | The name of the form of payment for the booking. |
| FormOfPaymentType | The type of the form of payment. |
| TicketMailingAddress | The mailing address for the booked ticket, if available. |
| TicketPickupLocation | The pickup location for the booked ticket, if available. |
| TicketPickupNumber | The confirmation number for the booked ticket, if available. |
| AirfareQuotes | List of stored airfare quotes for this booking. |
| Airline Tickets | List of airline tickets for this booking. |
| Charges | List of charges for this booking. |
| MiscChargeOrders | List of Miscellaneous AirCharges for this booking. |
| Passengers | This parent element contains a Passenger child element for each booked passenger. The Passenger child element contains the following child elements: NameFirst - The first name of the passenger. NameLast (optional) - The last name of the passenger. NameMiddle - The middle name of the passenger. NamePrefix - The passenger's name prefix. NameRemark - Additional details about the passenger's name. NameSuffix - The passenger's name suffix. NameTitle - The passenger's name title. TextName - The user's full name as entered in the booking tool if different from the name in the database. FrequentTravelerProgram - Passenger's loyalty programs. |
| PassPrograms | List of Pass Programs for this booking. |
| PhoneNumbers | List of Phone numbers associated with this booking. |
| RailPayments | List of Rail payments associated with rail segments in this booking. |
| Segments | This parent element will contain at least one of the following child elements: Air, Car, Hotel, Dining, Ride, Rail, Parking, Event. |
| Delivery | The method this booking was delivered. |
| WaitListSegments | The segments that the traveler is waitlisted for this booking. |
| Warning | The warnings associated with the booking. |
| WebAddresses | List of web addresses such as emails, pickup URLs, etc. associated with this booking. |
| BookingReferrer | BookingReferrer is used only in specific source tracking scenarios when there is a need to distinguish between bookings with the same BookingSources coming through different flows. Do not populate without coordinating with your technical contact. The supported values are: Concur Travel, Hipmunk, Sign-in with SAP Concur, Supplier Mobile, Supplier Web |
XML Example Request
POST /api/travel/trip/v1.1?userid_type=login_id&userid_value=cm@example.com HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
...
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<TripName>Trip from Dallas to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<Bookings>
<Booking>
<Segments>
<Car>
<Vendor>CQ</Vendor>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<ConfirmationNumber>F1672664579</ConfirmationNumber>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>M</Transmission>
<AirCondition>R</AirCondition>
<NumCars>1</NumCars>
<DiscountCode>346660</DiscountCode>
<DailyRate>44.0000</DailyRate>
<TotalRate>44.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
<Charges>
<Fixed>
<Description>Dropoff Fee</Description>
<Currency>USD</Currency>
<Amount>0.0000</Amount>
<IsPrimary>false</IsPrimary>
<SemanticsCode>DROPOFFFEE</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
</Fixed>
<RateWithAllowance>
<Currency>USD</Currency>
<Amount>44.0000</Amount>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<IsPrimary>true</IsPrimary>
<SemanticsCode>DAYS</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>1.0000</NumUnits>
<AllowanceNumUnits>250.0000</AllowanceNumUnits>
<AllowanceAmount>0.2400</AllowanceAmount>
<AllowanceIsUnlimited>false</AllowanceIsUnlimited>
</RateWithAllowance>
</Charges>
</Car>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
<Booking>
<Segments>
<Hotel>
<Vendor>CQ</Vendor>
<Status>GK</Status>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<ConfirmationNumber>3364214265</ConfirmationNumber>
<RateCode>LV4</RateCode>
<Name>CONCUR HOTEL</Name>
<HotelPropertyId>CONQ</HotelPropertyId>
<CheckinTime>03:00 PM</CheckinTime>
<CheckoutTime>12:00 PM</CheckoutTime>
<NumPersons>1</NumPersons>
<NumRooms>1</NumRooms>
<CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
<DailyRate>240.3500</DailyRate>
<Currency>USD</Currency>
<RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
<Charges>
<Rate>
<Currency>USD</Currency>
<Amount>240.3500</Amount>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<IsPrimary>false</IsPrimary>
<SemanticsCode>ROOMRATE</SemanticsCode>
<SemanticsVendorType>H</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>3.0000</NumUnits>
</Rate>
</Charges>
</Hotel>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<OriginalItinLocator>33491211</OriginalItinLocator>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
</Bookings>
</Itinerary>
XML Example Request of Agency Proposal
POST https://www.concursolutions.com/api/travel/trip/v1.1?userid_type=login_id&userid_value=cm@example.com HTTPS/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
...
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<TripName>Trip from Dallas to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<TripStatus>7</TripStatus>
<TravelRequestId>3339</TravelRequestId>
<CustomAttributes>
<CustomAttribute>
<ExternalId />
<DataType>Numeric</DataType>
<Name>ProposalBatchSize</Name>
<DisplayTitle />
<Data>3</Data>
<DisplayOnItinerary>true</DisplayOnItinerary>
</CustomAttribute>
<CustomAttribute>
<ExternalId />
<DataType>Numeric</DataType>
<Name>ProposalSequenceIndex</Name>
<DisplayTitle />
<Data>1</Data>
<DisplayOnItinerary>true</DisplayOnItinerary>
</CustomAttribute>
</CustomAttributes>
<Bookings>
<Booking>
<Segments>
<Car>
<Vendor>CQ</Vendor>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<ConfirmationNumber>F1672664579</ConfirmationNumber>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>M</Transmission>
<AirCondition>R</AirCondition>
<NumCars>1</NumCars>
<DiscountCode>346660</DiscountCode>
<DailyRate>44.0000</DailyRate>
<TotalRate>44.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
<Charges>
<Fixed>
<Description>Dropoff Fee</Description>
<Currency>USD</Currency>
<Amount>0.0000</Amount>
<IsPrimary>false</IsPrimary>
<SemanticsCode>DROPOFFFEE</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
</Fixed>
<RateWithAllowance>
<Currency>USD</Currency>
<Amount>44.0000</Amount>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<IsPrimary>true</IsPrimary>
<SemanticsCode>DAYS</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>1.0000</NumUnits>
<AllowanceNumUnits>250.0000</AllowanceNumUnits>
<AllowanceAmount>0.2400</AllowanceAmount>
<AllowanceIsUnlimited>false</AllowanceIsUnlimited>
</RateWithAllowance>
</Charges>
</Car>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
<Booking>
<Segments>
<Hotel>
<Vendor>CQ</Vendor>
<Status>GK</Status>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<ConfirmationNumber>3364214265</ConfirmationNumber>
<RateCode>LV4</RateCode>
<Name>CONCUR HOTEL</Name>
<HotelPropertyId>CONQ</HotelPropertyId>
<CheckinTime>03:00 PM</CheckinTime>
<CheckoutTime>12:00 PM</CheckoutTime>
<NumPersons>1</NumPersons>
<NumRooms>1</NumRooms>
<CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
<DailyRate>240.3500</DailyRate>
<Currency>USD</Currency>
<RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
<Charges>
<Rate>
<Currency>USD</Currency>
<Amount>240.3500</Amount>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<IsPrimary>false</IsPrimary>
<SemanticsCode>ROOMRATE</SemanticsCode>
<SemanticsVendorType>H</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>3.0000</NumUnits>
</Rate>
</Charges>
</Hotel>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<OriginalItinLocator>33491211</OriginalItinLocator>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
</Bookings>
</Itinerary>
Post Itinerary Details Response
| HTTP Responses | Supported Content Types |
|---|---|
| HTTP Status Codes | application/xml |
Content Body
When the trip is created successfully, the request will return the full posted trip details with the following additional elements inside the Itinerary parent element:
| Element | Description |
|---|---|
| id | The URI containing the trip ID. |
| ItinLocator | The Itinerary Locator value (trip ID without the URL). The ItinLocator value is used when updating an existing trip. |
| DateModifiedUtc | The UTC formatted date that this booking was last modified. |
| BookedVia | The GDS the itinerary was booked in. |
| DateBookedLocal | The date, in the traveler's local time, that the booking was made. |
Agency Proposal
The response will include the CustomAttributes element and its child elements if the request was an Agency Proposal.
XML Example of Successful Response
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
<ItinLocator>CNQR1234567890</ItinLocator>
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<TripName>Trip from Dallas to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<BookedVia>EveryGDS</BookedVia>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
<Bookings>
<Booking>
<Segments>
<Car>
<Vendor>CQ</Vendor>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<ConfirmationNumber>F1672664579</ConfirmationNumber>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>M</Transmission>
<AirCondition>R</AirCondition>
<NumCars>1</NumCars>
<DiscountCode>346660</DiscountCode>
<DailyRate>44.0000</DailyRate>
<TotalRate>44.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
<Charges>
<Fixed>
<Description>Dropoff Fee</Description>
<Currency>USD</Currency>
<Amount>0.0000</Amount>
<IsPrimary>false</IsPrimary>
<SemanticsCode>DROPOFFFEE</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
</Fixed>
<RateWithAllowance>
<Currency>USD</Currency>
<Amount>44.0000</Amount>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<IsPrimary>true</IsPrimary>
<SemanticsCode>DAYS</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>1.0000</NumUnits>
<AllowanceNumUnits>250.0000</AllowanceNumUnits>
<AllowanceAmount>0.2400</AllowanceAmount>
<AllowanceIsUnlimited>false</AllowanceIsUnlimited>
</RateWithAllowance>
</Charges>
</Car>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>ConcurCars</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>TravelSupplier</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
<Booking>
<Segments>
<Hotel>
<Vendor>CQ</Vendor>
<Status>GK</Status>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<ConfirmationNumber>3364214265</ConfirmationNumber>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<RateCode>LV4</RateCode>
<Name>CONCUR HOTEL</Name>
<HotelPropertyId>CONQ</HotelPropertyId>
<CheckinTime>00:00</CheckinTime>
<CheckoutTime>00:00</CheckoutTime>
<NumPersons>1</NumPersons>
<NumRooms>1</NumRooms>
<CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
<DailyRate>240.3500</DailyRate>
<Currency>USD</Currency>
<RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
<Charges>
<Rate>
<Currency>USD</Currency>
<Amount>240.3500</Amount>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<IsPrimary>false</IsPrimary>
<SemanticsCode>ROOMRATE</SemanticsCode>
<SemanticsVendorType>H</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>3.0000</NumUnits>
</Rate>
</Charges>
</Hotel>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>ConcurHotel</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<OriginalItinLocator>33491211</OriginalItinLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
</Bookings>
</Itinerary>
XML Example of Successful Response for Agency Proposal
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
<ItinLocator>CNQR1234567890</ItinLocator>
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<TripName>Trip from Dallas to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<BookedVia>EveryGDS</BookedVia>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
<Bookings>
<Booking>
<Segments>
<Car>
<Vendor>CQ</Vendor>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<ConfirmationNumber>F1672664579</ConfirmationNumber>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>M</Transmission>
<AirCondition>R</AirCondition>
<NumCars>1</NumCars>
<DiscountCode>346660</DiscountCode>
<DailyRate>44.0000</DailyRate>
<TotalRate>44.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
<Charges>
<Fixed>
<Description>Dropoff Fee</Description>
<Currency>USD</Currency>
<Amount>0.0000</Amount>
<IsPrimary>false</IsPrimary>
<SemanticsCode>DROPOFFFEE</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
</Fixed>
<RateWithAllowance>
<Currency>USD</Currency>
<Amount>44.0000</Amount>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<IsPrimary>true</IsPrimary>
<SemanticsCode>DAYS</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>1.0000</NumUnits>
<AllowanceNumUnits>250.0000</AllowanceNumUnits>
<AllowanceAmount>0.2400</AllowanceAmount>
<AllowanceIsUnlimited>false</AllowanceIsUnlimited>
</RateWithAllowance>
</Charges>
</Car>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>ConcurCars</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>TravelSupplier</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
<Booking>
<Segments>
<Hotel>
<Vendor>CQ</Vendor>
<Status>GK</Status>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<ConfirmationNumber>3364214265</ConfirmationNumber>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<RateCode>LV4</RateCode>
<Name>CONCUR HOTEL</Name>
<HotelPropertyId>CONQ</HotelPropertyId>
<CheckinTime>00:00</CheckinTime>
<CheckoutTime>00:00</CheckoutTime>
<NumPersons>1</NumPersons>
<NumRooms>1</NumRooms>
<CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
<DailyRate>240.3500</DailyRate>
<Currency>USD</Currency>
<RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
<Charges>
<Rate>
<Currency>USD</Currency>
<Amount>240.3500</Amount>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<IsPrimary>false</IsPrimary>
<SemanticsCode>ROOMRATE</SemanticsCode>
<SemanticsVendorType>H</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>3.0000</NumUnits>
</Rate>
</Charges>
</Hotel>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>ConcurHotel</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<OriginalItinLocator>33491211</OriginalItinLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
</Bookings>
<CustomAttributes>
<CustomAttribute>
<ExternalId />
<DataType>Numeric</DataType>
<Name>ProposalBatchSize</Name>
<DisplayTitle />
<Data>3</Data>
<DisplayOnItinerary>true</DisplayOnItinerary>
</CustomAttribute>
<CustomAttribute>
<ExternalId />
<DataType>Numeric</DataType>
<Name>ProposalSequenceIndex</Name>
<DisplayTitle />
<Data>1</Data>
<DisplayOnItinerary>true</DisplayOnItinerary>
</CustomAttribute>
</CustomAttributes>
</Itinerary>
Post Itinerary Cancellation Request
| Description | Supported Content Types |
|---|---|
| Cancels all segments in the supplied trip. This endpoint can be used to cancel trips for a user that is not the OAuth consumer. This is most often done when a travel supplier or Travel Management Company needs to cancel a trip on behalf of a user. The supplier or TMC must be registered with SAP Concur and have an SAP Concur account with one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard. |
application/xml |
Query Parameters - Required
- cancel?{tripId}
The identifier for the desired trip and the cancel keyword.
Example:
https://www.concursolutions.com/api/travel/trip/v1.1/cancel?tripId={_tripId_}
Query Parameters - Optional
- userid_type=login_id&userid_value={loginID}
The SAP Concur loginID of the user that owns the trip. The userid_type and userid_value parameters can only be used if the OAuth consumer has the user role listed above.
Example:
https://www.concursolutions.com/api/travel/trip/v1.1/cancel?tripId={_tripId_}&userid_type=login_id&userid_value={_loginID_}
| Request Headers - Required | Request Headers - Optional |
|---|---|
| Authorization header with OAuth token for a valid SAP Concur user. The OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. | None |
XML Example Request
POST /api/travel/trip/v1.1/cancel?tripId=CNQR1234567890 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...
POST Itinerary Cancellation
| HTTP Responses | Supported Content Types |
|---|---|
| HTTP Status Codes | application/xml |
Content Body
The request will return the full trip details for the cancelled trip. The trip will contain no segments, as those are all cancelled. The response includes the following additional elements inside the Itinerary parent element:
| Element | Description |
|---|---|
| id | The URI containing the trip ID. |
| ItinLocator | The Itinerary Locator value (trip ID without the URL). |
| ClientLocator | The identifier for the client. |
| DateModifiedUtc | The UTC formatted date that this booking was last modified. |
| BookedVia | The GDS the itinerary was booked in. |
| DateBookedLocal | The date, in the traveler's local time, that the booking was made. |
XML Example of Successful Response
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
<ItinLocator>CNQR1234567890</ItinLocator>
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<TripName>Trip from Dallas to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<BookedVia>EveryGDS</BookedVia>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
<Bookings>
<Booking>
<Segments/>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>ConcurCars</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>TravelSupplier</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
<Booking>
<Segments/>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>ConcurHotel</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<OriginalItinLocator>33491211</OriginalItinLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
</Bookings>
</Itinerary>
POST Booking Details
Creates a new booking or updates an existing booking. A new booking will be assigned to the specified trip, or if no trip is specified, the first itinerary that spans the booking dates. If no trip is specified and no itinerary exists that spans the booking dates, a new itinerary will be created.
This endpoint can be used to create/update bookings for a user that is not the OAuth consumer. This is most often done when a travel supplier or Travel Management Company needs to create/update a booking on behalf of a user. The supplier or TMC must be registered with SAP Concur, and must have an account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
POST /api/travel/booking/v1.0?tripId=12345678 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Request Parameters
Query Parameters - Optional
- tripId={tripId} The unique identifier for the trip. Supplied in order to add a booking to an existing trip.
- userid_type=login_id&userid_value={loginID} The SAP Concur login ID of the user who owns the booking. Only provided when the booking owner is not the OAuth consumer. Can only be used when the OAuth consumer has the required user role.
Examples:
https://www.concursolutions.com/api/travel/booking/v1.1?tripId={tripId}
https://www.concursolutions.com/api/travel/booking/v1.1?userid_type=login_id&userid_value={loginID}
Request Body Root Elements
The request contains a Booking parent element with the following child elements:
| Required Element | Description |
|---|---|
| BookingSource | The supplier's name. |
| ItinSourceName | The itinerary source. Format: TravelSupplier |
| RecordLocator | Record locator for this booking. This is often six alphanumeric characters but can have other formats depending on the booking source |
| Optional Element | Description |
|---|---|
| DateBookedLocal | The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| FormOfPaymentName | The name of the form of payment for the booking. |
| FormOfPaymentType | The type of the form of payment. |
| TicketMailingAddress | The mailing address for the booked ticket, if available. |
| TicketPickupLocation | The pickup location for the booked ticket, if available |
| TicketPickupNumber | The confirmation number to pick up the booked ticket, if available. |
| AirfareQuotes | List of stored airfare quotes for this booking. |
| AirlineTickets | List of Airline Tickets for this booking. |
| Charges | List of Charges for this booking. |
| MiscChargeOrders | List of Miscellaneous AirCharges for this booking. |
| Passengers | The Passengers element contains child element for each booked passenger. The description of each child element can be seen in a subsequent table. |
| PassPrograms | List of Pass Programs for this booking. |
| PhoneNumbers | List of Phone numbers associated with this booking. |
| RailPayments | List of Rail payments associated with rail segments in this booking. |
| Segments | List of Segments in this booking. This parent element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Event parent elements for the booking. |
| Delivery | The method this booking was delivered. |
| WaitListSegments | The segments that the traveler is waitlisted for this booking. |
| Warnings | The warnings associated with the booking. |
| WebAddresses | List of web addresses such as emails, pickup URLs, etc. associated with this booking |
| BookingReferrer | BookingReferrer is used only in specific source tracking scenarios when there is a need to distinguish between bookings with the same BookingSources coming through different flows. Do not populate without coordinating with your technical contact. The supported values are: Concur Travel, Hipmunk, Sign-in with SAP Concur, Supplier Mobile, Supplier Web |
Passenger Child Elements
| Required Element | Description |
|---|---|
| NameFirst | The first name of the passenger. |
| NameLast | The last name of the passenger. |
| Optional Element | Description |
|---|---|
| NameMiddle | The middle name of the passenger. |
| NamePrefix | The name prefix of the passenger. |
| NameRemark | Additional details about the passenger's name. |
| NameSuffix | The name suffix of the passenger. |
| NameTitle | The title of the passenger. |
| TextName | The user's full name as entered in the booking tool if different from the name in the database. |
| FrequentTravelerProgram | Passenger's loyalty programs |
Response
This function returns the full trip details.
If the end user updates an existing reservation which results in a new confirmation number, the old booking must be explicitly cancelled in addition to posting the new booking to SAP Concur. If the previous booking is not cancelled, the user will see both bookings in their SAP Concur trip list.
Examples
Example 1: XML Example Request
POST /api/travel/booking/v1.0?tripId=12345678 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
...
<Booking xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Segments>
<Car>
<Vendor>AL</Vendor>
<VendorName>Alamo</VendorName>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-23T12:00:00</EndDateLocal>
<StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
<EndDateUtc>2013-12-23T20:00:00</EndDateUtc>
<ConfirmationNumber>F16726AIUS</ConfirmationNumber>
<DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
<DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>A</Transmission>
<AirCondition>R</AirCondition>
<NumPersons>1</NumPersons>
<NumCars>1</NumCars>
<DiscountCode>4321</DiscountCode>
<DailyRate>35.0000</DailyRate>
<TotalRate>105.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
</Car>
</Segments>
<RecordLocator>PANAMA50</RecordLocator>
<BookingSource>Alamo</BookingSource>
<DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
<DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>TravelSupplier</ItinSourceName>
<Passengers>
<Passenger>
<PassengerKey>0</PassengerKey>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
</Booking>
Example 2: XML Example of Successful Response
<Itinerary xmlns="https://www.concursolutions.com/api/travel/trip/2010/06">
<id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
<ItinLocator>CNQR1234567890</ItinLocator>
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>TravelSupplier</ItinSourceName>
<TripName>Trip to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-23T23:59:00</EndDateLocal>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<BookedVia>EveryGDS</BookedVia>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
<Booking>
<Segments>
<Car>
<Vendor>AL</Vendor>
<VendorName>Alamo</VendorName>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-23T12:00:00</EndDateLocal>
<StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
<EndDateUtc>2013-12-23T20:00:00</EndDateUtc>
<ConfirmationNumber>F16726AIUS</ConfirmationNumber>
<DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
<DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>A</Transmission>
<AirCondition>R</AirCondition>
<NumPersons>1</NumPersons>
<NumCars>1</NumCars>
<DiscountCode>4321</DiscountCode>
<DailyRate>35.0000</DailyRate>
<TotalRate>105.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
</Car>
</Segments>
<RecordLocator>PANAMA50</RecordLocator>
<BookingSource>Alamo</BookingSource>
<DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
<DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>TravelSupplier</ItinSourceName>
<Passengers>
<Passenger>
<PassengerKey>0</PassengerKey>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
</Booking>
</Itinerary>
POST Booking Cancellation
Cancels an existing booking. By default, the OAuth consumer should be the owner of the booking. This endpoint can also be used to cancel bookings that the OAuth consumer does not own. This is most often done when a Travel Management Company needs to cancel bookings on behalf of a user. The TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
NOTE:
Booking records can only be updated by the booking source that created them. SAP Concur verifies the source information before processing the request.
POST /api/travel/booking/v1.1/cancel?bookingSource={FastTravel}&confirmationNumber={098765431} HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Request Parameters
Query Parameters - Required
- cancel?bookingSource={Supplier}
The cancel keyword and the unique identifier for the supplier, configured by SAP Concur during the application review. The bookingSource must match the Supplier Name associated with the booking.
- confirmationNumber={confnum}
The confirmation number for the booking to cancel.
Example:
https://www.concursolutions.com/api/travel/booking/v1.1/cancel?bookingSource={Supplier}&confirmationNumber={confnum}
Query Parameters - Optional
- userid_type=login_id&userid_value={loginID}
The SAP Concur login ID of the user who owns the booking. Only provided when the booking owner is not the OAuth consumer. Can only be used when the OAuth consumer has the required user role.
Example:
https://www.concursolutions.com/api/travel/booking/v1.1/cancel?bookingSource={Supplier}&confirmationNumber={confnum}&userid_type=login_id&userid_value={loginID}
Content Type
application/xml
Authorization Header
The authorization header must have an OAuth token for a valid SAP Concur user. The OAuth consumer must be registered as a Supplier or TMC with SAP Concur, and must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.
Response
This function returns the full booking details. If the booking is not found, the function returns a HTTP 404 error and the following element:
Status: This element contains the value: NotFound.
Examples
Examples 1: XML Example Request
POST /api/travel/booking/v1.1/cancel?bookingSource={FastTravel}&confirmationNumber={098765431} HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Examples 2: XML Example of Successful Response
<Car>
<Vendor>ZE</Vendor>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<TimeZoneId xsi:nil="true"/>
<StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
<EndDateUtc>2013-12-24T20:00:00</EndDateUtc>
<ConfirmationNumber>0987654321</ConfirmationNumber>
<CancellationNumber>1029384756</CancellationNumber>
<DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
<DateCancelledUtc>2012-07-25T14:21:35</DateCancelledUtc>
<DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
<UpgradedDateTime xsi:nil="true"/>
<IsUpgradeAllowed xsi:nil="true"/>
<FrequentTravelerId/>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>M</Transmission>
<AirCondition>R</AirCondition>
<PhoneNumber/>
<NumPersons xsi:nil="true"/>
<NumCars>1</NumCars>
<DiscountCode>346660</DiscountCode>
<Charges>
<Fixed>
<Description>Dropoff Fee</Description>
<Currency>USD</Currency>
<Amount>0.0000</Amount>
<StartDateLocal xsi:nil="true"/>
<IsPaid xsi:nil="true"/>
<SemanticsCode>DROPOFFFEE</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
</Fixed>
<RateWithAllowance>
<Currency>USD</Currency>
<Amount>44.0000</Amount>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<IsPaid xsi:nil="true"/>
<SemanticsCode>DAYS</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>1.0000</NumUnits>
<AllowanceUnit/>
<AllowanceNumUnits>250.0000</AllowanceNumUnits>
<AllowanceAmount>0.2400</AllowanceAmount>
<AllowanceIsUnlimited>false</AllowanceIsUnlimited>
</RateWithAllowance>
</Charges>
<Remarks/>
<PerDiemLocation/>
</Car>
Booking Object Elements
The booking elements contain many child elements. For ease of use, these elements are divided into the Core Elements, which are the most frequently used, and Additional Elements, which are not often used but are supported by the Itinerary web service. Some elements only appear if the travel supplier created the booking. Elements are marked as required if they must be supplied for a new booking.
NOTE: TripLink - Open Booking suppliers see a targeted subset of these fields. Refer to the documentation here for the TripLink - Open Booking supplier booking object elements.
Air Booking Elements
Core Elements - Required
| Element | Description |
|---|---|
| ClassOfService | The class of the booking. |
| ConfirmationNumber | The record locator or confirmation number for the flight from the airline. |
| EndCityCode | The IATA airport code for the end city of the booking. |
| EndDateLocal | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| FlightNumber | The flight number for the booking. |
| StartCityCode | The IATA airport code for the starting address for the booking. |
| StartDateLocal | The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| Vendor | The two letter GDS vendor code. Use $$ when not available. |
Core Elements - Optional
| Element | Description |
|---|---|
| CancellationNumber | The cancellation number from the vendor. This field should be set when you cancel a segment. |
| CancellationPolicy | The cancellation policy from the vendor. |
| Charges | The charges for this booking. Refer to the Charges Child Elements table. |
| DateCancelledUtc | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateCreatedUtc | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateModifiedUtc | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndDateUtc | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndGate | The arrival gate for the booking. |
| EndTerminal | The arrival terminal for the booking. |
| LegId | The leg ID of the booking. Leg IDs do not change on a connection. For each unique leg ID in the trip, all flights subsequent to the first segment with the same leg ID are connections. |
| Seats | The seats for the booking. This parent element contains an AirSeat element for each included seat. The AirSeat element contains the following child elements: PassengerRph - The passenger assigned to the seat. SeatNumber - The number of the seat. |
| StartDateUtc | The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| StartGate | The departure gate for the booking. |
| StartTerminal | The departure terminal for the booking. |
| Status | The GDS based booking status for the segment such as HK, HL, BK, etc. |
| TimeZone | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. |
Additional Elements - Optional
| Element | Description |
|---|---|
| AircraftCode | The code for the aircraft type. |
| Bags | The number of bags included in the booking. |
| Cabin | The section of the airplane for the booking. |
| CarbonEmissionLbs | The pounds of carbon emission for this booking. |
| CarbonModel | The model used to calculate the carbon emissions. |
| CheckedBaggage | Whether the booking includes checked baggage. |
| Duration | The duration of the booked flight. |
| ETicket | Whether the booking has an e-ticket. Format: Y/N |
| IsOpenSegment | Whether the segment is open. Format: True/False |
| IsPreferredVendor | If the airline is marked as a preferred property by the company. Format: True/False |
| IsUpgradeAllowed | Whether the booking can be upgraded. Format: True/False |
| Meals | The meals included in the booking. |
| Miles | The number of miles included in the booking. |
| Notes | Additional details about the booking. |
| OpenSegment | Additional information about the open segment. |
| OperatedByFlightNumber | Flight Number provided by the airline operating the flight on behalf of the booked airline. |
| OperatedByVendor | The airline operating the flight on behalf of the booked airline. |
| OperatedByVendorName | The name of the airline operating the flight on behalf of the booked airline. |
| Services | The services included in the booking. |
| SpecialInstructions | Additional instructions regarding the booking. Max Length: 256 |
| UpgradedDateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss |
Car Booking Elements
Core Elements - Required
| Element | Description |
|---|---|
| ConfirmationNumber | The confirmation number from the vendor. |
| EndDateLocal | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| StartDateLocal | The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| Vendor | The two letter GDS vendor code. |
Core Elements - Optional
| Element | Description |
|---|---|
| CancellationNumber | The cancellation number from the vendor. This field should be set when you cancel a segment. |
| CancellationPolicy | The cancellation policy from the vendor. |
| Charges | The charges for this booking. Refer to the Charges Child Elements table. |
| Currency | The 3-letter ISO 4217 currency code for the booking. |
| DailyRate | The daily rate for the booking. |
| DateCancelledUtc | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateCreatedUtc | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateModifiedUtc | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndCityCode | The IATA airport code for the ending address for the booking. |
| EndDateUtc | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndLatitude | The latitude for the ending location of the booking. |
| EndLongitude | The longitude for the ending location of the booking. |
| Notes | Additional information about the booking. |
| PhoneNumber | The phone number for the user. |
| RateCode | The rate code for the booking. |
| StartCityCode | The IATA airport code for the starting address for the booking. |
| StartDateUtc | The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| StartLatitude | The latitude for the starting location of the booking. |
| StartLongitude | The longitude for the starting location of the booking. |
| Status | The booking status. |
| TimeZone | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. |
| TotalRate | The total rate amount of the booking. |
| VendorName | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
Additional Elements - Optional
| Element | Description |
|---|---|
| AirCondition | The character code that indicates if car has an air conditioner. R for AC, N for No AC |
| Body | The character code to indicate how many passengers the car can seat. |
| Class | Character code to indicate the class of the car e.g. if it is economy, full size, compact, etc. Varies by Vendor |
| DiscountCode | The discount code used by the company/TMC to get a discounted rate. |
| DropoffCollectionAddress1 | The AddressLine1 for the dropoff address when the rental service offers dropoff. |
| DropoffCollectionAddressType | |
| DropoffCollectionCategory | |
| DropoffCollectionCity | City for the dropoff address when the rental service offers dropoff. |
| DropoffCollectionCityCode | The IATA airport code for the dropoff address when the rental service offers dropoff. |
| DropoffCollectionCountry | The country for the dropoff address when the rental service offers dropoff. |
| DropoffCollectionLatitude | The latitude for the dropoff address when the rental service offers dropoff. |
| DropoffCollectionLongitude | The longitude for the dropoff address when the rental service offers dropoff. |
| DropoffCollectionNumber | |
| DropoffCollectionPhoneNumber | The phone number for the dropoff address when the rental service offers dropoff. |
| DropoffCollectionPostalCode | The postal code for the dropoff address when the rental service offers dropoff. |
| DropoffCollectionState | The state for the dropoff address when the rental service offers dropoff. |
| EndAddress | The ending address for the booking. |
| EndAddress2 | The ending address for the booking. |
| EndCity | The ending address for the booking. |
| EndCloseTime | The closing time for the dropoff location. |
| EndCountry | The ending address for the booking. |
| EndLocation | The dropoff location. |
| EndOpenTime | The opening time of the dropoff location. |
| EndPhoneNumber | The phone number of the dropoff location. |
| EndPostalCode | The ending address for the booking. |
| EndState | The ending address for the booking. |
| FrequentTravelerId | The loyalty program ID for the user. |
| IsUpgradeAllowed | Whether the booking can be upgraded. Format: True/False |
| NumCars | The number of cars rented. |
| NumPersons | The number of people including the driver that the rental is for. |
| PickupDeliveryAddress1 | The AddressLine1 for the pickup address when the rental service offers pickup. |
| PickupDeliveryAddressType | |
| PickupDeliveryCategory | |
| PickupDeliveryCity | The city for the pickup address when the rental service offers pickup. |
| PickupDeliveryCityCode | The IATA airport code for the pickup address when the rental service offers pickup. |
| PickupDeliveryCountry | The country for the pickup address when the rental service offers pickup. |
| PickupDeliveryLatitude | The latitude for the pickup address when the rental service offers pickup. |
| PickupDeliveryLongitude | The longitude for the pickup address when the rental service offers pickup. |
| PickupDeliveryNumber | |
| PickupDeliveryPhoneNumber | The phone number for the pickup address when the rental service offers pickup. |
| PickupDeliveryPostalCode | The postal code for the pickup address when the rental service offers pickup. |
| PickupDeliveryState | The state for the pickup address when the rental service offers pickup. |
| RateType | The rate type for the booking. |
| SpecialEquipment | Any special equipment required by the renter. |
| SpecialInstructions | Additional instructions regarding the booking. Max Length: 256 |
| StartAddress | The starting address of the booking. |
| StartAddress2 | The starting address for the booking. |
| StartCity | The starting address for the booking. |
| StartCloseTime | The closing time for the pickup location. |
| StartCountry | The starting address for the booking. |
| StartLocation | The starting location of the booking. |
| StartOpenTime | The opening time for the pickup location. |
| StartPostalCode | The starting address for the booking. |
| StartState | The starting address for the booking. |
| Transmission | The character code that indicates if the car has auto-transmission. A for Auto, M for Manual |
| UpgradedDateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss |
Hotel Booking Elements
Core Elements - Required
| Element | Description |
|---|---|
| ConfirmationNumber | The confirmation number from the vendor. |
| EndDateLocal | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| Name | The hotel name for the booking. |
| StartCityCode | The IATA airport code for the starting address for the booking. |
| StartDateLocal | The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| Status | The booking status. |
| Vendor | The two letter GDS vendor code. |
Core Elements - Optional
| Element | Description |
|---|---|
| CancellationNumber | The cancellation number from the vendor. This field should be set when you cancel a segment. |
| CancellationPolicy | The cancellation policy from the vendor. |
| Charges | The charges for this booking. Refer to the Charges Child Elements table. |
| CheckinTime | The check in time for the hotel booking. |
| CheckoutTime | The check out time for the hotel booking. |
| Currency | The 3-letter ISO 4217 currency code for the booking. |
| DailyRate | Average per day rate for the hotel. If the rate varies over the duration, it can be specified using the charges model. |
| DateCancelledUtc | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateCreatedUtc | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateModifiedUtc | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndDateUtc | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| HotelPropertyId | The hotel's property ID. |
| Notes | Additional information about the booking. |
| NumPersons | The number of people the booking is for. |
| NumRooms | The number of rooms the booking is for. |
| PhoneNumber | The phone number for the booking. |
| RateCode | The rate code for the booking. |
| RoomDescription | The room description for the booking. Max Length: 200 |
| RoomType | The room type for the booking. |
| SpecialInstructions | Additional instructions regarding the booking. Max Length: 256 |
| StartAddress | The starting address of the booking. |
| StartAddress2 | The starting address for the booking. |
| StartCity | The starting address for the booking. |
| StartCountry | The starting address for the booking. |
| StartLatitude | The latitude for the starting location of the booking. |
| StartLongitude | The longitude for the starting location of the booking. |
| StartPostalCode | The starting address for the booking. |
| StartState | The starting address for the booking. |
| StartDateUtc | The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| TimeZone | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. |
| TotalRate | The total rate amount of the booking. |
Additional Elements - Optional
| Element | Description |
|---|---|
| EndCityCode | The IATA airport code for the ending address for the booking. |
| DiscountCode | The discount code for the booking. |
| FrequentTravelerId | The traveler’s ID for the frequent traveler reward program. |
| HadDeposit | Whether the booking had a deposit. Format: true/false |
| IsUpgradeAllowed | Whether the booking can be upgraded. Format: true/false |
| ModificationCode | The code for the modification to the booking. |
| PartnerMembershipId | The membership ID of the partner associated with the booking. |
| PassiveType | The type of the booking. |
| RateAccess | The rate access for the booking. |
| RateType | The rate type for the booking. |
| UpgradedDateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss |
| VendorFlags | Semi-colon-delimited list of flags for free hotel service flags. E.g. free breakfast (FB), internet (FI), Parking (FP), etc. If they were all present they can be concatenated as - FB;FI;FP; |
| VendorName | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
Dining Booking Elements
Core Elements - Required
| Element | Description |
|---|---|
| ConfirmationNumber | The confirmation number from the vendor. |
Core Elements - Optional
| Element | Description |
|---|---|
| CancellationNumber | The cancellation number from the vendor. This field should be set when you cancel a segment. |
| Charges | The charges for this booking. Refer to the Charges Child Elements table. |
| DateCancelledUtc | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateCreatedUtc | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateModifiedUtc | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndDateLocal | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| EndDateUtc | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| FrequentTravelerId | The loyalty program ID for the user. |
| IsUpgradeAllowed | Whether the booking can be upgraded. Format: true/false |
| Name | The name of the restaurant. Maximum length: 80 |
| Notes | Additional information about the booking. |
| NumPersons | The number of persons for the booking. |
| PhoneNumber | The restaurant phone number. |
| RestaurantId | The booking vendor’s restaurant ID. Maximum length: 50 |
| StartAddress | The restaurant address. Maximum length: 80 |
| StartAddress2 | The restaurant address. Maximum length: 80 |
| StartCity | The restaurant address. Maximum length: 50 |
| StartCountry | The restaurant address. |
| StartDateLocal | The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| StartDateUtc | The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| StartLatitude | The latitude of the restaurant. |
| StartLongitude | The longitude of the restaurant. |
| StartPostalCode | The restaurant address. Maximum length: 24 |
| StartState | The restaurant address. Maximum length: 50 |
| Status | The status of the segment. |
| TimeZone | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. |
| UpgradedDateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss |
| Vendor | The two letter GDS vendor code. |
| VendorName | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
Ride Booking Elements
Core Elements - Required
| Element | Description |
|---|---|
| ConfirmationNumber | The confirmation number from the vendor. |
| EndCityCode | The ending IATA airport code of the booking. |
| StartCityCode | The starting IATA airport code of the booking. |
| Vendor | The two letter GDS vendor code. One of the following vendor codes: |
Vendor Codes
| Code | Description |
|---|---|
| $R | RideCharge |
| AL | AddisonLee |
| DG | DeemGroundLimo |
| GC | GroundScope |
| GS | GroundSpan |
| LC | Limoscom |
| SQ | SummitQwest |
| SW | SummitQwest |
| TD | Tandem |
| TV | Transvip |
| $$ | unknown |
Core Elements - Optional
| Element | Description |
|---|---|
| CancellationNumber | The cancellation number from the vendor. This field should be set when you cancel a segment. |
| CancellationPolicy | The cancellation policy from the vendor. |
| Currency | The 3-letter ISO 4217 currency code for the booking. |
| DateCancelledUtc | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateCreatedUtc | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateModifiedUtc | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DropoffInstructions | Instructions regarding the booking. |
| Duration | The duration of the booking. |
| EndAddress | The ending address of the booking. |
| EndAddress2 | The ending address of the booking. |
| EndCity | The ending address of the booking. |
| EndCountry | The ending address of the booking. |
| EndDateLocal | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| EndDateUtc | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndLatitude | The latitude for the ending location of the booking. |
| EndLocation | The ending location of the booking. |
| EndLocationCode | The ending location code of the booking. |
| EndLocationName | The ending location name of the booking. |
| EndLongitude | The longitude of the ending point of the booking. |
| EndPostalCode | The ending address of the booking. |
| EndState | The ending address of the booking. |
| IsPersonal | Whether the segment is for personal travel. Format: true/false. |
| IsUpgradeAllowed | Whether the booking can be upgraded. Format: true/false |
| MeetingInstructions | The instructions for the meeting location of the booking. |
| Miles | The number of miles for the booking. |
| Name | The name on the booking. |
| Notes | Additional information about the booking. |
| NumberOfHours | The number of hours of the booking. |
| NumPersons | The number of people included in the booking. |
| OperatedByVendor | The operated by vendor for the booking. |
| PassiveCityCode | The passive city code of the booking. |
| PhoneNumber | The ride vendor phone number. |
| PickupInstructions | Instructions regarding the booking. |
| Rate | The rate for the booking. |
| RateDescription | The rate description for the booking. |
| RateNotes | The rate notes for the booking. |
| RateType | The rate type for the booking. |
| ReservationId | The booking vendor’s reservation ID. |
| SpecialInstructions | The special instructions for the ride. Max Length: 256 |
| StartAddress | The starting address of the booking. |
| StartAddress2 | The starting address of the booking. |
| StartCity | The starting address of the booking. |
| StartCountry | The starting address of the booking. |
| StartDateLocal | The booking starting time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| StartDateUtc | The booking starting time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| StartLatitude | The latitude of the booking start location. |
| StartLocation | The starting location of the booking. |
| StartLocationCode | The code of the starting location of the booking. |
| StartLocationName | The name of the starting location of the booking. |
| StartLongitude | The longitude of the booking start location. |
| StartPostalCode | The starting address of the booking. |
| StartState | The starting address of the booking. |
| Status | The status of the segment. |
| TimeZone | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. |
| UpgradedDateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss |
| VendorName | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
| Charges | The charges for this booking. Refer to the Charges Child Elements table. |
Rail Booking Elements
Core Elements - Required
| Element | Description |
|---|---|
| ConfirmationNumber | The confirmation number from the vendor. |
| StartDateLocal | The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss |
Core Elements - Optional
| Element | Description |
|---|---|
| Amenities | The booked amenities. |
| Cabin | The cabin identifier. |
| CancellationNumber | The cancellation number from the vendor. This field should be set when you cancel a segment. |
| CarbonEmissionLbs | The pounds of carbon emission for this booking. |
| CarbonModel | The model used to calculate the carbon emissions. |
| ClassOfService | The class of the booking. |
| Currency | The 3-letter ISO 4217 currency code for the booking. |
| DateCancelledUtc | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateCreatedUtc | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateModifiedUtc | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DiscountCode | The discount code for the booking. |
| Duration | The duration of the trip booked. |
| EndCity | The end city for the rail trip. |
| EndCityCode | The IATA airport code for the end city of the trip. |
| EndCountry | The country code for the booking. |
| EndDateLocal | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| EndDateUtc | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndLatitude | The latitude of the ending point of the booking. |
| EndLongitude | The longitude of the ending point of the booking. |
| EndPlatform | The ending platform location of the booking. |
| EndRailStation | The code for the ending station of the booking. |
| EndRailStationName | The name of the ending station of the booking. |
| ETicket | The e-ticket number. |
| FareType | The type of fare on the rail booking. |
| FrequentTravelerId | The traveler’s ID for the frequent traveler reward program. |
| IsUpgradeAllowed | Whether the booking can be upgraded. Format: true/false |
| LegId | The trip leg ID. |
| Meals | The booked meals. |
| Miles | The number of miles booked. |
| Notes | Additional information about the booking. |
| NumPersons | The number of persons booked for the trip. |
| NumStops | The number of stops in the booking. |
| OperatedByTrainNumber | The train identifier of the operating vendor of the booked trip. |
| OperatedByVendor | The operating vendor of the booked trip. |
| RateCode | The vendor's code for the rate of the booking. |
| RouteRestrictCode | The code to restrict the route of the booking. |
| SpecialInstructions | The instructions for the booking. Max Length: 256 |
| StartCity | The starting city of the booking. |
| StartCityCode | The IATA airport code for the starting city of the booking. |
| StartCountry | The starting country of the booking. |
| StartDateUtc | The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| StartLatitude | The latitude of the starting location of the booking. |
| StartLongitude | The longitude of the starting location of the booking. |
| StartPlatform | The starting platform location of the booking. |
| StartRailStation | The code of the starting station of the booking. |
| StartRailStationName | The name of the starting station of the booking. |
| Status | The booking status. |
| TimeZone | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. |
| TotalRate | The total rate amount of the booking. |
| TrainNumber | The number for the booked train. |
| TrainTypeCode | The code for the type of train used in the booking. |
| TrainTypeName | The name of the type of train used in the booking. |
| TransportMode | The transport mode of the booking. |
| UpgradedDateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss |
| Vendor | The two letter GDS vendor code. |
| VendorName | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
| WagonNumber | The wagon number of the train car. |
| Charges | The charges for this booking. Refer to the Charges Child Elements table. |
| Seats | The booked seats. This parent element contains a RailSeat element for each included seat. The RailSeat element has the following child elements: |
RailSeat Child Elements
| Element | Description |
|---|---|
| Amenities | The amenities for the seat. |
| BerthPosition | The berth location of the seat. |
| Deck | Which deck the seat is on. |
| FacingForward | Whether the seat is facing forward. |
| FareSpaceComfort | The space around the seat. |
| PassengerRph | Which passenger the seat is assigned to. |
| SeatNumber | The number of the seat. |
| SeatPosition | The location of the seat. |
| SpaceType | The type of space around the seat. |
| Status | The status of the seat booking. |
| WagonNumber | The number of the wagon the seat is on. |
| WagonType | The type of wagon the seat is on. |
Parking Booking Elements
Core Elements - Required
| Element | Description |
|---|---|
| ConfirmationNumber | The confirmation number from the vendor. |
| StartDateLocal | The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss |
Core Elements - Optional
| Element | Description |
|---|---|
| CancellationNumber | The cancellation number from the vendor. This field should be set when you cancel a segment. |
| ClassOfService | The class of the booking. |
| Currency | The 3-letter ISO 4217 currency code for the booking. |
| DateCancelledUtc | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateCreatedUtc | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateModifiedUtc | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndDateLocal | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| EndDateUtc | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| FrequentTravelerId | The traveler’s ID for the frequent traveler reward program. |
| IsUpgradeAllowed | Whether the booking can be upgraded. Format: true/false |
| Notes | Additional information about the booking. |
| OperatedByVendor | The operating vendor of the booking. |
| ParkingLocationId | The location of the parking booking. |
| PhoneNumber | The parking phone number. |
| Pin | The PIN number for the booking. |
| RateCode | The vendor's code for the rate of the booking. |
| StartAddress | The starting address of the booking. |
| StartAddress2 | The starting address of the booking. |
| StartCity | The starting address of the booking. |
| StartCityCode | The IATA airport code for the starting city of the booking. |
| StartCountry | The starting address of the booking. |
| StartDateUtc | The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| StartLocation | The parking location. |
| StartPostalCode | The starting address of the booking. Maximum length: 24 |
| StartState | The starting address of the booking. Maximum length: 50 |
| Status | The booking status. |
| TimeZone | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. |
| TotalRate | The total rate amount of the booking. |
| UpgradedDateTime | The date and time the booking was upgraded. Format: YYYY-MM-DDThh:mm:ss |
| Vendor | The two letter GDS vendor code. |
| VendorName | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
| Charges | The charges for this booking. Refer to the Charges Child Elements table. |
Travel Booking
NOTE: This booking type is used by the Concur Travel Request product to store the main destination for the trip without specifying a transport type.
Core Elements - Required
| Element | Description |
|---|---|
| EndDateLocal | The booking ending time and date, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
| StartCity | The starting address of the booking. |
| StartCityCode | The IATA airport code for the starting city of the booking. |
| StartDateLocal | The starting date of travel for this segment, in the local time of to the starting point. Format: YYYY-MM-DDThh:mm:ss |
Core Elements - Optional
| Element | Description |
|---|---|
| CancellationNumber | The cancellation number from the vendor. This field should be set when you cancel a segment. |
| ConfirmationNumber | The confirmation number from the vendor. |
| Currency | The 3-letter ISO 4217 currency code for the booking. |
| DailyRate | Average per day rate for the booking. If the rate varies over the duration, it can be specified using the charges model. |
| DateCancelledUtc | The date the booking was cancelled, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateCreatedUtc | The date the booking was created, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| DateModifiedUtc | The date the booking was modified, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndAddress | The ending address of the booking. |
| EndAddress2 | The ending address of the booking. |
| EndCity | The ending address of the booking. |
| EndCityCode | The IATA airport code for the ending city of the booking. |
| EndCountry | The ending address of the booking. |
| EndDateUtc | The booking ending time and date, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| EndLatitude | The latitude for the ending location of the booking. |
| EndLocation | The ending location of the booking. |
| EndLongitude | The longitude of the ending point of the booking. |
| EndPostalCode | The ending address of the booking. |
| EndState | The ending address of the booking. |
| TransportMode | The transport mode of the booking. |
| Notes | Additional information about the booking. |
| NumPersons | The number of persons booked for the trip. |
| PhoneNumber | The parking phone number. |
| SpecialInstructions | The instructions for the booking. Max Length: 256 |
| StartAddress | The starting address of the booking. |
| StartAddress2 | The starting address of the booking. |
| StartCity | The starting address of the booking. |
| StartCityCode | The IATA airport code for the starting city of the booking. |
| StartCountry | The starting address of the booking. |
| StartDateUtc | The starting date of travel for this segment, in UTC. Format: YYYY-MM-DDThh:mm:ss |
| StartLatitude | The latitude of the starting location of the booking. |
| StartLongitude | The longitude of the starting location of the booking. |
| StartPostalCode | The starting address of the booking. Maximum length: 24 |
| StartState | The starting address of the booking. Maximum length: 50 |
| Status | The booking status. |
| TimeZone | The time zone of the booking. Format: One of the supported Olson or Windows Time Zones. |
| TotalRate | The total rate amount of the booking. |
| Vendor | The two letter GDS vendor code. |
| VendorName | The name of the vendor. When using the Unknown Vendor Code ($$), this value appears as the vendor in the itinerary. |
| Charges | The charges for this booking. Refer to the Charges Child Elements table. |
| Seats | The seats for the booking. This parent element contains an TravelSeat element for each included seat. The TravelSeat element contains the following child elements: |
TravelSeat Elements
| Element | Description |
|---|---|
| PassengerRph | The passenger assigned to the seat. |
| SeatNumber | The number of the seat. |
Charges Child Elements
Core Elements - Required
Percent - The Percent of Fixed Charges
This parent element contains the following child elements:
| Element | Description |
|---|---|
| Amount | The total amount for the rate for the booking. |
| Currency | The 3-letter ISO 4217 currency code for the total amount. |
| Description | The description for the rate. |
| IsPaid | Whether the rate has been paid. Format: true/false. |
| IsPrimary | Indicates whether the charge is the Primary or Main rate. For example, if one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be primary. Format: true/false. |
| SemanticsCode | Indicates the charge category for the line item. |
| SemanticsVendorType | The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail |
| StartDateLocal | The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss |
| Vendor | The vendor for the booking charge. |
| VendorChargeCode | The vendor's code for the charge |
Fixed - The Fixed Charges
This parent element contains the following child elements:
| Element | Description |
|---|---|
| Currency | The 3-letter ISO 4217 currency code for the total amount. |
| Description | The description for the fixed amount. |
| IsPaid | Whether the fixed amount has been paid. Format: true/false. |
| IsPrimary | Whether the fixed amount is primary. Format: true/false. |
| SemanticsCode | Indicates the charge category for the line item. Refer to the Semantics and Vendor Codes document for more information. |
| SemanticsVendorType | The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail |
| StartDateLocal | The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss |
| Vendor | The vendor applying the booking charge. |
| VendorChargeCode | The vendor's code for the charge. |
Rate - The Rate for the Booking
This parent element contains the following child elements:
| Element | Description |
|---|---|
| Amount | The total amount for the rate for the booking. |
| Currency | The 3-letter ISO 4217 currency code for the total amount. |
| Description | The description for the rate. |
| IsPaid | Whether the rate has been paid. Format: true/false. |
| IsPrimary | Whether the rate is primary. Format: true/false. |
| NumUnits | The number of units expected for the charge. For instance, 3 days |
| PerUnit | The unit of measure for the charge. Values represent rates like per DAY, WEEK, or MONTH |
| SemanticsCode | Indicates the charge category for the line item. Refer to the Semantics and Vendor Codes document for more information. |
| SemanticsVendorType | The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail |
| StartDateLocal | The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss |
| Vendor | The vendor for the booking charge. |
| VendorChargeCode | The vendor's code for the charge. |
RateWithAllowance - The Rate for the Booking, Including any Travel Allowances
This parent element contains the following child elements:
| Element | Description |
|---|---|
| AllowanceAmount | The cost of overage fees when the allowance is exceeded. For example, if the allowance is 5000 miles, the cost could be $0.02 per mile. The overage must be in the same currency as the basic rate. |
| AllowanceIsUnlimited | Whether the allowance is unlimited. Format: true/false. |
| AllowanceNumUnits | The number of units for the allowance associated with the charge. For example, 5000 miles. |
| AllowanceUnit | The unit of measure for the allowance associated with the charge. For example, a car weekly rate might allow 5000 miles included in the rate. |
| Amount | The total amount for the rate for the booking. |
| Currency | The 3-letter ISO 4217 currency code for the total amount. |
| Description | The description for the rate. |
| IsPaid | Whether the rate has been paid. Format: true/false. |
| IsPrimary | Indicates whether the charge is the Primary or Main rate. For example, if one of the rates is the actual rate and the rest are penalties, the actual rate should be set as IsPrimary. Only one charge in a set should be primary. Format: true/false. |
| NumUnits | The number of units expected for the charge. For instance, 3 days. |
| PerUnit | The unit of measure for the charge. Values represent rates like per DAY, WEEK, or MONTH |
| SemanticsCode | Indicates the charge category for the line item. Refer to the Semantics and Vendor Codes document for more information. |
| SemanticsVendorType | The vendor type: H=Hotel, C=Car, A=Air, G=Ground, R=Rail |
| StartDateLocal | The start date of the booking, in the user's local time. Format: YYYY-MM-DDThh:mm:ss |
| Vendor | The vendor for the booking charge. |
| VendorChargeCode | The vendor's code for the charge. |
Time Zone Formats
Olson Time Zones
| Africa/Cairo | Africa/Casablanca | Africa/Harare | Africa/Luanda |
| Africa/Nairobi | Africa/Windhoek | America/Anchorage | America/Argentina/Buenos_Aires |
| America/Asuncion | America/Bahia | America/Bogota | America/Buenos_Aires |
| America/Caracas | America/Chicago | America/Chihuahua | America/Denver |
| America/Godthab | America/Guyana | America/Halifax | America/Indianapolis |
| America/Los_Angeles | America/Manaus | America/Mexico_City | America/Montevideo |
| America/New_York | America/Phoenix | America/Regina | America/Santiago |
| America/Sao_Paulo | America/St_Johns | America/Swift_Current | America/Tijuana |
| Asia/Almaty | Asia/Amman | Asia/Baghdad | Asia/Baku |
| Asia/Bangkok | Asia/Beirut | Asia/Calcutta | Asia/Colombo |
| Asia/Damascus | Asia/Dhaka | Asia/Irkutsk | Asia/Jerusalem |
| Asia/Kabul | Asia/Kamchatka | Asia/Karachi | Asia/Karachi |
| Asia/Katmandu | Asia/Krasnoyarsk | Asia/Magadan | Asia/Muscat |
| Asia/Novosibirsk | Asia/Rangoon | Asia/Riyadh | Asia/Seoul |
| Asia/Shanghai | Asia/Singapore | Asia/Taipei | Asia/Tbilisi |
| Asia/Tehran | Asia/Tokyo | Asia/Ulaanbaatar | Asia/Vladivostok |
| Asia/Yakutsk | Asia/Yekaterinburg | Asia/Yerevan | Atlantic/Azores |
| Atlantic/Cape_Verde | Atlantic/South_Georgia | Australia/Adelaide | Australia/Brisbane |
| Australia/Darwin | Australia/Hobart | Australia/Perth | Australia/Sydney |
| Etc/GMT+12 | Etc/GMT-11 | Etc/GMT-2 | Europe/Athens |
| Europe/Berlin | Europe/Helsinki | Europe/Istanbul | Europe/Kaliningrad |
| Europe/London | Europe/Minsk | Europe/Moscow | Europe/Paris |
| Europe/Prague | Europe/Sarajevo | GMT | GMT-1200 |
| Indian/Mauritius | Pacific/Apia | Pacific/Auckland | Pacific/Fiji |
| Pacific/Guadalcanal | Pacific/Guam | Pacific/Honolulu | Pacific/Tongatapu |
| UTC |
Windows Time Zones
| Africa/Cairo | Africa/Casablanca | Africa/Harare | Africa/Luanda |
| Africa/Nairobi | Africa/Windhoek | America/Anchorage | America/Argentina/Buenos_Aires |
| America/Asuncion | America/Bahia | America/Bogota | America/Buenos_Aires |
| America/Caracas | America/Chicago | America/Chihuahua | America/Denver |
| America/Godthab | America/Guyana | America/Halifax | America/Indianapolis |
| America/Los_Angeles | America/Manaus | America/Mexico_City | America/Montevideo |
| America/New_York | America/Phoenix | America/Regina | America/Santiago |
| America/Sao_Paulo | America/St_Johns | America/Swift_Current | America/Tijuana |
| Asia/Almaty | Asia/Amman | Asia/Baghdad | Asia/Baku |
| Asia/Bangkok | Asia/Beirut | Asia/Calcutta | Asia/Colombo |
| Asia/Damascus | Asia/Dhaka | Asia/Irkutsk | Asia/Jerusalem |
| Asia/Kabul | Asia/Kamchatka | Asia/Karachi | Asia/Karachi |
| Asia/Katmandu | Asia/Krasnoyarsk | Asia/Magadan | Asia/Muscat |
| Asia/Novosibirsk | Asia/Rangoon | Asia/Riyadh | Asia/Seoul |
| Asia/Shanghai | Asia/Singapore | Asia/Taipei | Asia/Tbilisi |
| Asia/Tehran | Asia/Tokyo | Asia/Ulaanbaatar | Asia/Vladivostok |
| Asia/Yakutsk | Asia/Yekaterinburg | Asia/Yerevan | Atlantic/Azores |
| Atlantic/Cape_Verde | Atlantic/South_Georgia | Australia/Adelaide | Australia/Brisbane |
| Australia/Darwin | Australia/Hobart | Australia/Perth | Australia/Sydney |
| Etc/GMT+12 | Etc/GMT-11 | Etc/GMT-2 | Europe/Athens |
| Europe/Berlin | Europe/Helsinki | Europe/Istanbul | Europe/Kaliningrad |
| Europe/London | Europe/Minsk | Europe/Moscow | Europe/Paris |
| Europe/Prague | Europe/Sarajevo | GMT | GMT-1200 |
| Indian/Mauritius | Pacific/Apia | Pacific/Auckland | Pacific/Fiji |
| Pacific/Guadalcanal | Pacific/Guam | Pacific/Honolulu | Pacific/Tongatapu |
| UTC |
Trip Endpoint
Trips
The Trips resource represents itineraries in the Concur Travel system. TripLink suppliers use this resource to display a subset of the full booking fields.
Version
1.1
URI
/travel/trip/v1.1/{query_parameters}
Scope
In order to obtain itinerary data when making Itinerary API calls, the value of the OAuth scope parameter must be set to: ITINER
Operations
Get Trip Summaries
The Get Itinerary Summaries endpoint is used for retrieving trip summaries for the traveler whose account is associated with the OAuth access token used to make the API call. This endpoint can also be used to get trip summaries for a different user or the whole company. This is usually done when a Travel Management Company (TMC) needs to get trip summaries on behalf of a user or company.
Best Practices
- When extracting past data:
- Extract a month of trip summaries to gauge volume. If hundreds are returned, then adjust extraction to weekly.
- Do not extract more than a year of data at any given time regardless of the volume. For longer look backs, extract 6 month segments maximum at a time.
- Do not multi-thread requests to retrieve multiple pages of data. Concurrent requests will impact your application’s performance.
- Itineraries change frequently. Changes do not necessarily indicate that the traveler modified their trip. If your application works with upcoming or in progress trips, be aware that you must evaluate the individual segments to determine whether it is a material change for your application.
- This API will only return itineraries that have been sent to Concur Travel; this includes travel booked within Concur Travel, TripIt, on TripLink supplier sites, and most bookings from your travel agency. Some customers may have multiple booking options which may mean not all employee trips are available via this API. A good rule of thumb: if the traveler sees the itinerary in their “trips” list, then you can retrieve it from this API.
Request
GET /travel/trip/v1.1/{query_parameters}
Query Parameters
All query parameters are optional.
To identify a specific user by login ID or XMLSyncID, you can specify the following request parameters:
| Parameter Name | Parameter Type | Data Type | Description |
|---|---|---|---|
startDate |
date |
dateTime |
The URL-encoded start date (in Coordinated Universal Time, or UTC) for the trip. Format: YYYY-MM-DD. If no query parameters are provided, the start date is set to today's date - 30 days. The request will only return trips that are ongoing during the provided dates, either starting on the date, or starting before the date and ongoing during the provided date. |
endDate |
date |
dateTime |
The URL-encoded UTC end date for the trip. Format: YYYY-MM-DD. If no query parameters are provided, the end date is set to today's date + 12 months. The request will only return trips that are ongoing during the provided dates, either ending on the date, or starting before the date and ongoing during the provided date. |
createdAfterDate |
date |
dateTime |
The URL-encoded UTC date for when the trip was created. The query string will return trips created on or after this date. Used with the createdBeforeDate for finding trips created during a date range. Format: YYYY-MM-DD. |
createdBeforeDate |
date |
dateTime |
The URL-encoded UTC date for when the trip was created. The query string will return trips created on or before this date. Used with the createdAfterDate for finding trips created during a date range. Format: YYYY-MM-DD. |
lastModifiedDate |
date |
dateTime |
The last modified UTC date of the trips and their associated bookings. This query string will return only the trips where the trip or any of its associated bookings have a last modified date that is greater or equal to the supplied time. The provided date/time can be anytime between now and the first date of trip creation in the database. The format is either the date or the date and time combined. |
bookingType |
type |
string |
The trip includes at least one booking of this type. Format: Air, Car, Dining, Hotel, Parking, Rail, or Ride. |
userid_type=login |
userid |
string |
The loginID is the user's SAP Concur login ID. This parameter can only be used if the OAuth consumer has one of the user roles listed above. |
userid_value |
userid |
string |
The userid_value of ALL can be sent to get trip summaries for all users at the company. This parameter can only be used if the OAuth consumer has one of the user roles listed above. |
includeMetadata |
true/false |
string |
The includeMetadata query parameter combined with the ItemsPerPage and Page query parameters cause the response to be divided into pages. The response is wrapped in a ConcurResponse parent element, with both the response details and the paging metadata included. If the ItemsPerPage query parameter is not sent, the response will default to 200 if the Page query parameter is sent, or 1000 if the Page query parameter is not set. If the Page query parameter is not sent, the response will default to page 1. |
ItemsPerPage |
number |
integer |
The includeMetadata query parameter combined with the ItemsPerPage and Page query parameters will cause the response to be divided into pages. The response will be wrapped in a ConcurResponse parent element, with both the response details and the paging metadata included. If the ItemsPerPage query parameter is not sent, the response will default to 200 if the Page query parameter is sent, or 1000 if the Page query parameter is not set. If the Page query parameter is not sent, the response will default to page 1. |
includeVirtualTrip |
flag |
integer |
Virtual trips are segments booked offline through the Concur Request product. Set the includeVirtualTrip query parameter to 1 to include those trips in the list. |
includeCanceledTrips |
true/false |
string |
The includeCanceledTrips query parameter will cause the request to also return trips with a status of Canceled. When this query parameter is set to true, the response will include the TripStatus element. |
includeGuestBookings |
true/false |
string |
The includeGuestBookings query parameter will cause the request to show guest bookings if set to true. It is set to false by default. |
Here are some examples of how to format GET requests using a combination of these query parameters:
- To get trip summaries for the entire company:
https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={_startdate_}&endDate={_enddate_}_&_createdAfterDate={_date_}&createdBeforeDate={_date_}&lastModifiedDate={_date_}&bookingType={_type_}&userid_type=login&userid_value=ALL
The access token used to make the API call must be associated with an account that has the Admin user role.
- To get trip summaries for the account associated with the app making the call:
https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={_startdate_}&endDate={_enddate_}_&_createdAfterDate={_date_}&createdBeforeDate={_date_}&lastModifiedDate={_date_}&bookingType={_type_}
The access token used to make the API call is associated with the account for the app making the call.
- To get trip summaries for a user with the specified login credentials:
https://www.concursolutions.com/api/travel/trip/v1.1/?startDate={_startdate_}&endDate={_enddate_}_&_createdAfterDate={_date_}&createdBeforeDate={_date_}&lastModifiedDate={_date_}&bookingType={_type_}&userid_type=login_id&userid_value={_loginID_}
The access token used to make the API call is associated with the SAP Concur account with the specified login credentials.
Headers
Authorization Header (Required)
Authorization: OAuth {access_token}
Where access_token is the OAuth 2.0 access token of the user whose itinerary information you want to retrieve. If you want to access company-wide itinerary information, the SAP Concur user account associated with the OAuth 2.0 access token must have one of these roles: Web Services Administrator for Professional or Can Administer for Standard.
Accept Header (optional)
application/xml
Get Trip Summaries Response Schema
The response returns an ItineraryInfoList parent element with an ItineraryInfo child element for each trip summary for the specified traveler. If the includeMetadata and ItemsPerPage query parameters are included in the request, the response will include a ConnectResponse parent element which contains a MetaData element with paging information and a Data element with an ItineraryInfoList child element. The response for this operation can be divided into pages for easier processing.
Data Elements
| Element Name | Data Type | Description |
|---|---|---|
ItineraryInfoList |
element |
Parent element with an ItineraryInfo child element for each trip summary for the specified traveler. |
ItineraryInfoList Elements
| Element Name | Data Type | Description |
|---|---|---|
ItineraryInfo |
element |
Parent element with the information about an itinerary for the specified user. |
ItineraryInfo Elements
| Element Name | Data Type | Description |
|---|---|---|
TripId |
string |
Encrypted trip identifier value. |
TripName |
string |
Name of the trip. |
TripStatus |
string |
The status of the trip. This element only appears if the includeCanceledTrips query parameter is used in the request. |
StartDateLocal |
dateTime |
The start date of the trip in the starting location’s timezone. Format: YYYY-MM-DDThh:mm:ss. |
EndDateLocal |
dateTime |
The end date of the trip in the ending location’s timezone. Format: YYYY-MM-DDThh:mm:ss. |
DateModifiedUtc |
dateTime |
The UTC date that this trip was last modified. Format: YYYY-MM-DDThh:mm:ss. |
UserLoginId |
string |
The user's login to SAP Concur. This element appears in the response of the GET /api/travel/trip/v1.1 operation when the OAuth 2.0 is access token is associated with an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard. |
id |
string |
Trip ID URI with encrypted ID. |
Metadata Element
The parent element of the paging information.
Paging Elements
| Element Name | Data Type | Description |
|---|---|---|
TotalPages |
integer |
The total number of pages the query returned. |
TotalItems |
integer |
The total number of itineraries the query returned. |
CurrentPage |
integer |
The page number for the set of results in the current response. |
ItemsPerPage |
integer |
The number of items set to display per page. |
PreviousPageURL |
string |
The URI to the previous page of results. This element will be empty when there are no previous pages. |
NextPageURL |
string |
The URI to the next set of results. This element will be empty when there are no next pages. |
Examples
Example 1: Get Trip Summaries by Start and End Date
Request
GET /api/travel/trip/v1.1/?startDate=2012%2F02%2F01&endDate=2013%2F12%2F31 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...
Response
HTTP/1.1 200 OK
Content-Type: application/xml
...
<?xml version="1.0" encoding="utf-8"?>
<ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ItineraryInfo>
<TripId>naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</TripId>
<TripName>Trip from Baltimore to New York</TripName>
<StartDateLocal>2012-02-15T09:00:00</StartDateLocal>
<EndDateLocal>2012-02-21T17:30:00</EndDateLocal>
<UserLoginId>cm@example.com</UserLoginId>
<DateModifiedUtc>2012-02-14T17:13:07</DateModifiedUtc>
<id>https://www.concursolutions.com/api/travel/trip/v1.1/naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</id>
</ItineraryInfo>
<ItineraryInfo>
<TripId>I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</TripId>
<TripName>Trip from Baltimore to Seattle</TripName>
<StartDateLocal>2012-03-26T09:00:00</StartDateLocal>
<EndDateLocal>2012-03-29T17:30:00</EndDateLocal>
<DateModifiedUtc>2012-03-24T19:00:00</DateModifiedUtc>
<UserLoginId>cm@example.com</UserLoginId>
<id>https://www.concursolutions.com/api/travel/trip/v1.1/I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</id>
</ItineraryInfo>
</ItineraryInfoList>
Example 2: Get Trip Summary by Booking Type and Start Date Request
This request returns trip summaries for trips that started by the specified date for the specified booking type.
Request
GET /api/travel/trip/v1.1/?startDate=2015%2F01%2F01&bookingType=Air HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...
Response
HTTP/1.1 200 OK
Content-Type: application/xml
...
<?xml version="1.0" encoding="utf-8"?>
<ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ItineraryInfo>
<TripId>I2uwiJJw8r7OwCIQOb2SHTsozwBsSie9W</TripId>
<TripName>Trip by air from Seattle to San Francisco</TripName>
<StartDateLocal>2015-01-01T12:30:00</StartDateLocal>
<EndDateLocal>2015-01-05T10:30:00</EndDateLocal>
<UserLoginId>cm@example.com</UserLoginId>
<DateModifiedUtc>2014-12-23T11:10:00</DateModifiedUtc>
<id>https://www.concursolutions.com/api/travel/trip/
v1.1/I2uwiJJw8r7OwCIQOb2SHTsozwBsSie9W</id>
</ItineraryInfo>
</ItineraryInfoList>
Example 3: Get Trip Summary by Created Date
This requests returns trip summaries created after the specified date.
Request
GET /api/travel/trip/v1.1/?createdAfterDate=2015%2F02%2F13 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Response
HTTP/1.1 200 OK
Content-Type: application/xml
...
<?xml version="1.0" encoding="utf-8"?>
<ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ItineraryInfo>
<TripId>BWjCIJJw8r7OwCIQOb2SHTsozwBsWlSie9</TripId>
<TripName>Trip by air from Los Angeles to Mexico City</TripName>
<StartDateLocal>2015-03-09T18:45:00</StartDateLocal>
<EndDateLocal>2015-03-30T08:00:00</EndDateLocal>
<UserLoginId>cm@example.com</UserLoginId>
<DateModifiedUtc>2015-01-28T09:30:00</DateModifiedUtc>
<id>https://www.concursolutions.com/api/travel/trip/
v1.1/BWjCIJJw8r7OwCIQOb2SHTsozwBsWlSie9</id>
</ItineraryInfo>
</ItineraryInfoList>
Example 4: Get Trip Summary with Paging
This request is used for dividing the response into pages for easier processing.
Request
GET /api/travel/trip/v1.1/?createdAfterDate=2012%2F02%2F01&includeMetadata=true&ItemsPerPage=2&Page=1 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Response
The response returns a ConnectResponse parent element which contains a MetaData element with paging information and a Data element with an ItineraryInfoList child element.
HTTP/1.1 200 OK
Content-Type: application/xml
...
<ConnectResponse>
<Metadata>
<Paging>
<TotalPages>38</TotalPages>
<TotalItems>187</TotalItems>
<CurrentPage>2</CurrentPage>
<ItemsPerPage>2</ItemsPerPage>
<PreviousPageURL>https://www.concursolutions.com/api/travel/trip/v1.1/?
createdAfterDate=2012%2F02%2F01&
itemsPerPage=5&page=3&includeMetaData=true</PreviousPageURL>
<NextPageURL>https://www.concursolutions.com/api/travel/trip/v1.1/?
createdAfterDate=2012%2F02%2F01&
itemsPerPage=5&page=1&includeMetaData=true</NextPageURL>
</Paging>
</Metadata>
<Data>
<ItineraryInfoList xmlns="http://www.concursolutions.com/api/travel/trip/2010/06" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ItineraryInfo>
<TripId>naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</TripId>
<TripName>Trip from Baltimore to New York</TripName>
<StartDateLocal>2012-02-15T09:00:00</StartDateLocal>
<EndDateLocal>2012-02-21T17:30:00</EndDateLocal>
<UserLoginId>cm@example.com</UserLoginId>
<DateModifiedUtc>2012-02-14T17:13:07</DateModifiedUtc>
<id>https://www.concursolutions.com/api/travel/trip/v1.1/naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</id>
</ItineraryInfo>
<ItineraryInfo>
<TripId>I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</TripId>
<TripName>Trip from Baltimore to Seattle</TripName>
<StartDateLocal>2012-03-26T09:00:00</StartDateLocal>
<EndDateLocal>2012-03-29T17:30:00</EndDateLocal>
<DateModifiedUtc>2012-03-24T19:00:00</DateModifiedUtc>
<UserLoginId>cm@example.com</UserLoginId>
<id>https://www.concursolutions.com/api/travel/trip/v1.1/I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL</id>
</ItineraryInfo>
</ItineraryInfoList>
</Data>
</ConnectResponse>
Get Trip Details
The Get Itinerary Details endpoint is used for getting details for the specified trip. The elements included in the response vary as follows:
- Some elements, such as
AirlineTicketsorRailPayments, appear only for bookings of the appropriate type. For exampleAirlineTicketsappears in the response only for air bookings andRailPayments, for rail bookings. - Amount values, such as Rate or Tax, appear only if the requestor is the source of the booking. All other suppliers will not receive the amount elements associated with the bookings.
- Some elements, such as
SabreDKNumber, appear only if the booking was created by the relevant GDS. - Some elements are vendor-specific and appear only in responses for the associated vendor.
This topic describes the full set of possible elements that can be returned. No itinerary can contain all of the possible elements, so the response will always be a subset of all the possible returned values.
By default, when calling this API, the SAP Concur account associated with the OAuth access token used to make the API call should be the owner of the trip. This endpoint can also be used to get details for trips that the OAuth consumer does not own. This is most often done when a TMC needs to get trip details on behalf of a user. The TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
Request
GET /travel/trip/v1.1/trip_ID?[systemFormat=system_format|&userid_type=login|&user_id=login_ID]
Path Parameters
| Parameter Name | Data Type | Description |
|---|---|---|
trip_ID |
string |
Required: The identifier for the desired trip. This identifier is returned as the value of the ID element when getting trip summaries. For example, if the returned value of the ID element is I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL, then the URI for the request is /travel/trip/v1.1/I2uwiJJw8r7Owl3IWlSie9WIelxhAhwi. |
Query Parameters
| Parameter Name | Data Type | Description |
|---|---|---|
systemFormat |
string |
Optional: Format of the response for a different system. The supported value is Tripit. The format for the request URI using this query parameter is /travel/trip/v1.1/trip_ID?systemFormat=Tripit. |
userid_type |
string |
Optional: The type of user identification to use. Possible value is: login. |
userid_value |
string |
Optional: The user's login ID. This parameter must be provided in conjunction with the userid_type parameter. The userid_type and userid_value parameters can only be used if the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard. The format for the request URI using the userid_type and userid_value query parameters is /travel/trip/v1.1/trip_ID?userid_type=login&userid_value=login_ID. |
Headers
Authorization Header (Required)
Authorization: OAuth {access_token}
Where access_token is the OAuth 2.0 access token of the user whose itinerary information you want to retrieve. If you want to access company-wide itinerary information, the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.
Accept Header (Optional)
application/xml
Get Trip Details Response Schema
The response returns subset of the elements described in the following tables depending on the parameters used in the request and the status and details for the itinerary. The response can be formatted for TripIt, using the systemformat query string.
Parent Elements
| Element Name | Data Type | Description |
|---|---|---|
id |
string |
Trip ID URI with encrypted ID. |
ItinLocator |
string |
The itinerary locator. This element is now deprecated and only supported for backward compatibility. |
ClientLocator |
string |
Represents the unique identifier of the trip in an external (non-Concur) system. Maximum length 32 characters. |
ItinSourceName |
string |
The itinerary source. Format: TravelSupplier. |
TripName |
string |
Name of the trip. Maximum length 255 characters. |
Comments |
string |
Comments for this itinerary. Maximum length 512 characters. |
StartDateLocal |
dateTime |
The start date of the trip in the starting location’s timezone. Format: YYYY-MM-DDThh:mm:ss. |
EndDateLocal |
dateTime |
The end date of the trip in the ending location’s timezone. Format: YYYY-MM-DDThh:mm:ss. |
DateCreatedUtc |
dateTime |
The date that this trip was created, in UTC. Format: YYYY-MM-DDThh:mm:ss. |
DateModifiedUtc |
dateTime |
The UTC date that this trip was last modified. Format: YYYY-MM-DDThh:mm:ss. |
BookedVia |
string |
The booking method for the trip. |
BookedByFirstName |
string |
The first name of the person who booked the trip. |
BookedByLastName |
string |
The last name of the person who booked the trip. |
DateBookedLocal |
dateTime |
The date the trip was booked, in the local time of the booking location. Format: YYYY-MM-DDThh:mm:ss. |
CancelComments |
string |
The comments provided if the itinerary is cancelled. Maximum length: 256 characters. |
Description |
string |
The trip description. Maximum length: 512 characters. |
EndDateUtc |
dateTime |
The end date of the trip, in UTC. Format: YYYY-MM-DDThh:mm:ss. |
IsPersonal |
boolean |
Whether the trip is a Business or Leisure trip. Format: true/false. |
ProjectName |
string |
The associated project name for the trip. Maximum length: 255 characters. |
StartDateUtc |
dateTime |
The start date of the trip, in UTC. Format: YYYY-MM-DDThh:mm:ss. |
RuleViolations |
array |
The list of rule violations associated with the itinerary. This parent element contains a RuleViolation child element for each associated rule violation. |
Status |
string |
The status of the itinerary. One of the following: 0- Confirmed; 1- Ticketed by agent; 2- Canceled. |
Bookings |
array |
A parent element that contains a Booking child element for each booking associated with this itinerary. |
Booking Element
| Element Name | Data Type | Description |
|---|---|---|
Segments |
array |
List of segments in this booking. The child elements included in this element vary depending on whether a TMC, SAP Concur client, third-party developer, or TripLink supplier is requesting the itinerary details: For TMCs, clients, and third-party developers, the Segments element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Travel parent elements. For TripLink suppliers, the Segments element contains one or more Air, Car, Hotel, or Ride parent elements. |
Passengers |
array |
Contains a Passenger child element for each included passenger. For more information on the Passengers element, see Create a New Trip. |
RecordLocator |
string |
The unique identifier for a booking. This is often six alphanumeric characters, but can have other formats depending on the booking source. |
BookingSource |
string |
The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place. |
DateModifiedUtc |
dateTime |
The date the booking was last modified, in UTC. Format: YYYY-MM-DDThh:mm:ss. |
DateBookedLocal |
dateTime |
The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss. |
ItinSourceName |
string |
The itinerary source. Format: TravelSupplier. |
PassengerCount |
integer |
The number of passengers included in the booking. |
Examples
Example 1: Get Trip Details for a Trip ID
Request
GET /api/travel/trip/v1.1/CNQR1234567890 HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...
Response
HTTP/1.1 200 OK
Content-Type: application/xml
...
<?xml version="1.0" encoding="utf-8"?>
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
<ItinLocator>CNQR1234567890</ItinLocator>
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<TripName>Trip from Dallas to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<BookedVia>EveryGDS</BookedVia>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
<Bookings>
<Booking>
<Segments>
<Car>
<Vendor>CQ</Vendor>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<ConfirmationNumber>F1672664579</ConfirmationNumber>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>M</Transmission>
<AirCondition>R</AirCondition>
<NumCars>1</NumCars>
<DiscountCode>346660</DiscountCode>
<DailyRate>44.0000</DailyRate>
<TotalRate>44.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
<Charges>
<Fixed>
<Description>Dropoff Fee</Description>
<Currency>USD</Currency>
<Amount>0.0000</Amount>
<IsPrimary>false</IsPrimary>
<SemanticsCode>DROPOFFFEE</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
</Fixed>
<RateWithAllowance>
<Currency>USD</Currency>
<Amount>44.0000</Amount>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<IsPrimary>true</IsPrimary>
<SemanticsCode>DAYS</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>1.0000</NumUnits>
<AllowanceNumUnits>250.0000</AllowanceNumUnits>
<AllowanceAmount>0.2400</AllowanceAmount>
<AllowanceIsUnlimited>false</AllowanceIsUnlimited>
</RateWithAllowance>
</Charges>
</Car>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>ConcurCars</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>TravelSupplier</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
<Booking>
<Segments>
<Hotel>
<Vendor>CQ</Vendor>
<Status>GK</Status>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<ConfirmationNumber>3364214265</ConfirmationNumber>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<RateCode>LV4</RateCode>
<Name>CONCUR HOTEL</Name>
<HotelPropertyId>CONQ</HotelPropertyId>
<CheckinTime>00:00</CheckinTime>
<CheckoutTime>00:00</CheckoutTime>
<NumPersons>1</NumPersons>
<NumRooms>1</NumRooms>
<CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
<DailyRate>240.3500</DailyRate>
<Currency>USD</Currency>
<RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
<Charges>
<Rate>
<Currency>USD</Currency>
<Amount>240.3500</Amount>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<IsPrimary>false</IsPrimary>
<SemanticsCode>ROOMRATE</SemanticsCode>
<SemanticsVendorType>H</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>3.0000</NumUnits>
</Rate>
</Charges>
</Hotel>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>ConcurHotel</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<OriginalItinLocator>33491211</OriginalItinLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
</Bookings>
</Itinerary>
Example 2: Get Trip Details in TripIt Format
Request
GET /travel/trip/v1.1/73014481752?systemFormat=Tripit HTTP/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...
Response
<?xml version="1.0" encoding="utf-8"?>
<Response>
<Trip>
<id>73014481752</id>
<relative_url>/api/travel/trip/v1.1/73014481752</relative_url>
<start_date>2013-08-21</start_date>
<end_date>2013-08-24</end_date>
<display_name>Strategy Team meeting</display_name>
<is_private>true</is_private>
</Trip>
<AirObject>
<booking_site_conf_num>RL10001005</booking_site_conf_num>
<booking_site_name>Concur Travel</booking_site_name>
<booking_site_phone></booking_site_phone>
<booking_site_url>https://www.concursolutions.com</booking_site_url>
<record_locator>4294993825</record_locator>
<supplier_conf_num>CN10001005</supplier_conf_num>
<supplier_contact></supplier_contact>
<supplier_email_address></supplier_email_address>
<supplier_name></supplier_name>
<supplier_phone></supplier_phone>
<supplier_url></supplier_url>
<is_purchased>1</is_purchased>
<notes></notes>
<restrictions></restrictions>
<total_cost></total_cost>
<Segment>
<StartDateTime>
<date>2013-08-21</date>
<time>07:45:00</time>
</StartDateTime>
<EndDateTime>
<date>2013-08-21</date>
<time>13:03:00</time>
</EndDateTime>
<start_airport_code>PHX</start_airport_code>
<start_gate>A11</start_gate>
<start_terminal>4</start_terminal>
<end_airport_code>ORD</end_airport_code>
<end_gate>F8</end_gate>
<end_terminal>2</end_terminal>
<marketing_airline>US</marketing_airline>
<marketing_flight_number>1</marketing_flight_number>
<aircraft>320</aircraft>
<duration></duration>
<distance>1433</distance>
<notes></notes>
<seats></seats>
<service_class>Economy</service_class>
<stops>Nonstop</stops>
</Segment>
<Segment>
<StartDateTime>
<date>2013-08-24</date>
<time>13:55:00</time>
</StartDateTime>
<EndDateTime>
<date>2013-08-24</date>
<time>16:58:00</time>
</EndDateTime>
<start_airport_code>ORD</start_airport_code>
<start_gate></start_gate>
<start_terminal></start_terminal>
<end_airport_code>PHX</end_airport_code>
<end_gate></end_gate>
<end_terminal></end_terminal>
<marketing_airline>US</marketing_airline>
<marketing_flight_number>1728</marketing_flight_number>
<aircraft>A320</aircraft>
<duration></duration>
<distance></distance>
<notes></notes>
<seats></seats>
<service_class>Economy</service_class>
<stops> stops</stops>
</Segment>
<Traveler>
<first_name>William</first_name>
<middle_name></middle_name>
<last_name>Never</last_name>
<frequent_traveler_num></frequent_traveler_num>
<frequent_traveler_supplier></frequent_traveler_supplier>
<ticket_num></ticket_num>
</Traveler>
</AirObject>
</Response>
Create a New Trip
This endpoint is used for creating a new trip. To create a new trip, the specified dates in the content body can only span the trip to be created and cannot span an existing trip. To create or update a trip on behalf of a user, the OAuth access token used to make the API call should be associated with the SAP Concur account of that user. The TripLink supplier or TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
Request
POST /travel/trip/v1.1?[userid_type=login&user_id=login_ID]
Request Parameters
| Parameter Name | Data Type | Description |
|---|---|---|
userid_type |
string |
Optional: The type of user identification to use. Possible value is: login_id. |
userid_value |
string |
Optional: The value for the user identification type. Currently the only available type is login_id so the value is the login credentials. This parameter must be provided in conjunction with the userid_type parameter. The userid_type and userid_value parameters can only be used if the user account associated with the OAuth 2.0 access token is associated with an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard. The format for the request URI using the userid_type and userid_value query parameters is /travel/trip/v1.1/trip_ID?userid_type=login&userid_value=login_ID. |
Headers
Authorization Header (required)
Authorization: OAuth {access_token}
Where access_token is the OAuth 2.0 access token of the user whose trip you want to create or update. If you want to access company-wide itinerary information, the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.
Create New Trip Request Schema
| Element Name | Required or Optional | TripLink | Data Type | Description |
|---|---|---|---|---|
Itinerary |
required | Y | ItineraryType |
The root element for a trip. For this endpoint, it contains the following elements: ClientLocator, ItinSourceName, TripName, Comments, StartDateLocal, EndDateLocal, BookedByFirstName, BookedByLastName, Bookings. |
TripName |
required | Y | string |
Name of the trip. Maximum length: 255 characters. |
TripStatus |
required | Y | unsignedByte |
The status of the trip. One of the following: 0 - Confirmed; 1 - Ticketed; 2 - Canceled; 6 - Proposal; 7 - Booked Proposal. This element only appears if the includeCanceledTrips query parameter is used in the request. |
RecordLocator |
required | Y | string |
The unique identifier for a booking. This is often six alphanumeric characters, but can have other formats depending on the booking source. |
BookingSource |
required | Y | string |
The name of the booking source for this booking. A booking source is a textual name the system uses to track where a booking took place. This could be a GDS, OTA, Vendor code for a Supplier website, or Supplier Direct Connect API. For TripLink suppliers, this is the supplier's name. |
StartDateLocal |
optional | Y | dateTime |
The start date of the trip in the starting location’s timezone. Format: YYYY-MM-DDThh:mm:ss. |
EndDateLocal |
optional | Y | dateTime |
The end date of the trip in the ending location’s timezone. Format: YYYY-MM-DDThh:mm:ss. |
BookedByFirstName |
optional | Y | string |
The first name of the person who booked the trip. |
BookedByLastName |
optional | Y | string |
The last name of the person who booked the trip. |
Bookings |
optional | Y | array |
A parent element that contains a Booking child element for each booking associated with this itinerary. |
Booking |
optional | Y | array |
A child element of the Bookings element which in turn contains the following child elements: Segments, Passengers, RecordLocator, BookingSource, DateModifiedUtc, DateBookedLocal, ItinSourceName, and PassengerCount. |
Segments |
optional | Y | array |
List of segments in this booking. The child elements included in this element vary depending on whether a TMC, client, third-party developer, or TripLink supplier is requesting the itinerary details: For TMCs, clients, and third-party developers, the Segments element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Travel parent elements. For TripLink suppliers, the Segments element contains one or more Air, Car, Hotel, or Ride parent elements. |
Comments |
optional | Y | string |
Comments for the itinerary. Maximum length: 512 characters. |
ItinSourceName |
optional | N | string |
The itinerary source. Format: TravelSupplier. |
BookingOwner |
optional | Y | string |
Indicates the tool that supplied the booking to Concur Travel. |
Source |
optional | N/A | string |
This element is obsolete. It is supported for backward compatibility only. |
DateBookedLocal |
optional | Y | dateTime |
The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss. |
FormOfPaymentName |
optional | - | string |
The name of the form of payment for the booking. |
FormOfPaymentType |
optional | - | string |
The type of the form of payment. |
TicketMailingAddress |
optional | - | - | The mailing address for the booked ticket, if available. |
TicketPickupLocation |
optional | - | - | The pickup location for the booked ticket, if available. |
TicketPickupNumber |
optional | - | - | The confirmation number for the booked ticket, if available. |
AirfareQuotes |
optional | - | array |
List of stored airfare quotes for this booking. |
Airline Tickets |
optional | - | array |
List of airline tickets for this booking. |
Charges |
optional | - | array |
List of charges for this booking. |
MiscChargeOrders |
optional | - | array |
List of miscellaneous air charges for this booking. |
Passengers |
optional | Y | array |
Contains a Passenger child element for each included passenger. The Passenger child element in turn contains the following required child elements: NameFirst, NameLast, and the following optional elements: NameMiddle, NamePrefix, NameRemark, NameSuffix, NameTitle, TextName, and FrequentTravelerProgram. |
PassPrograms |
optional | - | array |
List of pass programs for this booking. This parent element has a PassProgram child element for each pass program associated with the booking. The PassProgram parent element has the following child elements: Amount, Name, Type, UserFirstName, and UserLastname. |
PhoneNumbers |
optional | - | array |
List of phone numbers associated with this booking. This parent element has a PhoneNumberData child element for each phone number associated with the booking. The PhoneNumberData parent element has the following child elements: PassengerRPH, PhoneNumber, Type, and Description. |
RailPayments |
optional | - | array |
List of rail payments associated with rail segments in this booking. It has the following child elements: RailPayment that represents the payment information for a rail booking and RailAdjustment for the amount adjusted for a rail booking. |
Segments |
optional | Y | array |
List of segments in this booking. The child elements included in this element vary depending on whether a TMC, client, third-party developer, or TripLink supplier is requesting the itinerary details: For TMCs, clients, and third-party developers, the Segments element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Travel parent elements. For TripLink suppliers, the Segments element contains one or more Air, Car, Hotel, or Ride parent elements. |
Delivery |
optional | - | - | The method this booking was delivered. |
WaitListSegments |
optional | - | - | The segments that the traveler is waitlisted for this booking. |
Warning |
optional | - | - | The warnings associated with the booking. |
WebAddresses |
optional | - | - | List of web addresses such as emails, pick-up URLs, and so on associated with this booking. |
Create New Trip Response Schema
The response returns an HTTP status code and if the trip is created successfully, it also returns the full posted trip details with the following additional elements inside the Itinerary parent element:
| Element Name | Data Type | TripLink | Description |
|---|---|---|---|
id |
string |
Y | The URI including the trip ID. |
ItinLocator |
string |
Y | The Itinerary Locator value (trip ID without the URL). The ItinLocator value is used when updating an existing trip. |
DateModifiedUtc |
dateTime |
Y | The UTC formatted date that this booking was last modified. |
BookedVia |
string |
Y | The booking method or the GDS the itinerary was booked in. |
DateBookedLocal |
dateTime |
Y | The date, in the traveler’s local time, that the booking was made. |
Examples
Example 1: TMC Creates a Trip for User Using Their Login Credentials
This example shows how to create a trip for a user using their login credentials.
Request
POST /api/travel/trip/v1.1?userid_type=login_id&userid_value=cm@example.com HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
...
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<TripName>Trip from Dallas to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<Bookings>
<Booking>
<Segments>
<Car>
<Vendor>CQ</Vendor>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<ConfirmationNumber>F1672664579</ConfirmationNumber>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>M</Transmission>
<AirCondition>R</AirCondition>
<NumCars>1</NumCars>
<DiscountCode>346660</DiscountCode>
<DailyRate>44.0000</DailyRate>
<TotalRate>44.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
<Charges>
<Fixed>
<Description>Dropoff Fee</Description>
<Currency>USD</Currency>
<Amount>0.0000</Amount>
<IsPrimary>false</IsPrimary>
<SemanticsCode>DROPOFFFEE</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
</Fixed>
<RateWithAllowance>
<Currency>USD</Currency>
<Amount>44.0000</Amount>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<IsPrimary>true</IsPrimary>
<SemanticsCode>DAYS</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>1.0000</NumUnits>
<AllowanceNumUnits>250.0000</AllowanceNumUnits>
<AllowanceAmount>0.2400</AllowanceAmount>
<AllowanceIsUnlimited>false</AllowanceIsUnlimited>
</RateWithAllowance>
</Charges>
</Car>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
<Booking>
<Segments>
<Hotel>
<Vendor>CQ</Vendor>
<Status>GK</Status>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<ConfirmationNumber>3364214265</ConfirmationNumber>
<RateCode>LV4</RateCode>
<Name>CONCUR HOTEL</Name>
<HotelPropertyId>CONQ</HotelPropertyId>
<CheckinTime>03:00 PM</CheckinTime>
<CheckoutTime>12:00 PM</CheckoutTime>
<NumPersons>1</NumPersons>
<NumRooms>1</NumRooms>
<CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
<DailyRate>240.3500</DailyRate>
<Currency>USD</Currency>
<RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
<Charges>
<Rate>
<Currency>USD</Currency>
<Amount>240.3500</Amount>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<IsPrimary>false</IsPrimary>
<SemanticsCode>ROOMRATE</SemanticsCode>
<SemanticsVendorType>H</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>3.0000</NumUnits>
</Rate>
</Charges>
</Hotel>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<OriginalItinLocator>33491211</OriginalItinLocator>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
</Bookings>
</Itinerary>
Response
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
<ItinLocator>CNQR1234567890</ItinLocator>
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<TripName>Trip from Dallas to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<BookedVia>EveryGDS</BookedVia>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
<Bookings>
<Booking>
<Segments>
<Car>
<Vendor>CQ</Vendor>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<ConfirmationNumber>F1672664579</ConfirmationNumber>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>M</Transmission>
<AirCondition>R</AirCondition>
<NumCars>1</NumCars>
<DiscountCode>346660</DiscountCode>
<DailyRate>44.0000</DailyRate>
<TotalRate>44.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
<Charges>
<Fixed>
<Description>Dropoff Fee</Description>
<Currency>USD</Currency>
<Amount>0.0000</Amount>
<IsPrimary>false</IsPrimary>
<SemanticsCode>DROPOFFFEE</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
</Fixed>
<RateWithAllowance>
<Currency>USD</Currency>
<Amount>44.0000</Amount>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<IsPrimary>true</IsPrimary>
<SemanticsCode>DAYS</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>1.0000</NumUnits>
<AllowanceNumUnits>250.0000</AllowanceNumUnits>
<AllowanceAmount>0.2400</AllowanceAmount>
<AllowanceIsUnlimited>false</AllowanceIsUnlimited>
</RateWithAllowance>
</Charges>
</Car>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>ConcurCars</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>TravelSupplier</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
<Booking>
<Segments>
<Hotel>
<Vendor>CQ</Vendor>
<Status>GK</Status>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<ConfirmationNumber>3364214265</ConfirmationNumber>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<RateCode>LV4</RateCode>
<Name>CONCUR HOTEL</Name>
<HotelPropertyId>CONQ</HotelPropertyId>
<CheckinTime>00:00</CheckinTime>
<CheckoutTime>00:00</CheckoutTime>
<NumPersons>1</NumPersons>
<NumRooms>1</NumRooms>
<CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
<DailyRate>240.3500</DailyRate>
<Currency>USD</Currency>
<RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
<Charges>
<Rate>
<Currency>USD</Currency>
<Amount>240.3500</Amount>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<IsPrimary>false</IsPrimary>
<SemanticsCode>ROOMRATE</SemanticsCode>
<SemanticsVendorType>H</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>3.0000</NumUnits>
</Rate>
</Charges>
</Hotel>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>ConcurHotel</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<OriginalItinLocator>33491211</OriginalItinLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
</Bookings>
</Itinerary>
Example 2: TripLink Supplier Creates a Trip
This example shows how a TripLink supplier creates a trip.
Request
POST /api/travel/trip/v1.1/ HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
...
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<TripName>Trip from Dallas to Seattle</TripName>
<TripStatus>HK</TripStatus>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<Bookings>
<Booking>
<Segments>
<Car>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
</Car>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
</Booking>
<Booking>
<Segments>
<Hotel>
<Status>GK</Status>
<StartCityCode>SEA</StartCityCode>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<TimeZoneId>Pacific</TimeZoneId>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<StartCity>Seattle</StartCity>
<StartCountry>US</StartCountry>
</Hotel>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
</Booking>
</Bookings>
</Itinerary>
Response
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
<ItinLocator>CNQR1234567890</ItinLocator>
<TripName>Trip from Dallas to Seattle</TripName>
<TripStatus>HK</TripStatus>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<BookedVia>EveryGDS</BookedVia>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
<Bookings>
<Booking>
<Segments>
<Car>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
</Car>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
</Booking>
<Booking>
<Segments>
<Hotel>
<Status>GK</Status>
<StartCityCode>SEA</StartCityCode>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<TimeZoneId>Pacific</TimeZoneId>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<StartCity>Seattle</StartCity>
<StartCountry>US</StartCountry>
</Hotel>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
</Booking>
</Bookings>
</Itinerary>
Example 3: Third-Party Developer Creates a Trip Using the Access Token Used to Make the API Call
This example shows how to create a trip for a user whose account is associated with the access token used to make the API call.
Request
POST https://www.concursolutions.com/api/travel/trip/v1.1 HTTPS/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
...
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<TripName>Trip from Dallas to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<TripStatus>7</TripStatus>
<TravelRequestId>3339</TravelRequestId>
<CustomAttributes>
<CustomAttribute>
<ExternalId />
<DataType>Numeric</DataType>
<Name>ProposalBatchSize</Name>
<DisplayTitle />
<Data>3</Data>
<DisplayOnItinerary>true</DisplayOnItinerary>
</CustomAttribute>
<CustomAttribute>
<ExternalId />
<DataType>Numeric</DataType>
<Name>ProposalSequenceIndex</Name>
<DisplayTitle />
<Data>1</Data>
<DisplayOnItinerary>true</DisplayOnItinerary>
</CustomAttribute>
</CustomAttributes>
<Bookings>
<Booking>
<Segments>
<Car>
<Vendor>CQ</Vendor>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<ConfirmationNumber>F1672664579</ConfirmationNumber>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>M</Transmission>
<AirCondition>R</AirCondition>
<NumCars>1</NumCars>
<DiscountCode>346660</DiscountCode>
<DailyRate>44.0000</DailyRate>
<TotalRate>44.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
<Charges>
<Fixed>
<Description>Dropoff Fee</Description>
<Currency>USD</Currency>
<Amount>0.0000</Amount>
<IsPrimary>false</IsPrimary>
<SemanticsCode>DROPOFFFEE</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
</Fixed>
<RateWithAllowance>
<Currency>USD</Currency>
<Amount>44.0000</Amount>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<IsPrimary>true</IsPrimary>
<SemanticsCode>DAYS</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>1.0000</NumUnits>
<AllowanceNumUnits>250.0000</AllowanceNumUnits>
<AllowanceAmount>0.2400</AllowanceAmount>
<AllowanceIsUnlimited>false</AllowanceIsUnlimited>
</RateWithAllowance>
</Charges>
</Car>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
<Booking>
<Segments>
<Hotel>
<Vendor>CQ</Vendor>
<Status>GK</Status>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<ConfirmationNumber>3364214265</ConfirmationNumber>
<RateCode>LV4</RateCode>
<Name>CONCUR HOTEL</Name>
<HotelPropertyId>CONQ</HotelPropertyId>
<CheckinTime>03:00 PM</CheckinTime>
<CheckoutTime>12:00 PM</CheckoutTime>
<NumPersons>1</NumPersons>
<NumRooms>1</NumRooms>
<CancellationPolicy>Cxl 1 day prior to Arrival</CancellationPolicy>
<DailyRate>240.3500</DailyRate>
<Currency>USD</Currency>
<RoomDescription>1 KING BED ACCESSIBLE ROOM - K1RRC</RoomDescription>
<Charges>
<Rate>
<Currency>USD</Currency>
<Amount>240.3500</Amount>
<StartDateLocal>2013-12-21T23:59:00</StartDateLocal>
<IsPrimary>false</IsPrimary>
<SemanticsCode>ROOMRATE</SemanticsCode>
<SemanticsVendorType>H</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>3.0000</NumUnits>
</Rate>
</Charges>
</Hotel>
</Segments>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>TravelBookings.com</BookingSource>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<OriginalItinLocator>33491211</OriginalItinLocator>
<ItinSourceName>ConcurConnectAPI</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
</Bookings>
</Itinerary>
Response
The response is the same as in Example 1.
Update a Trip
Creates a new trip or updates an existing trip. A new trip will be created if the trip dates span no existing trip and the request doesn’t include a tripId. If a tripId is included in the URI it will update the specified trip. The full trip information is included in the update request, which replaces the existing trip.
This endpoint can be used to create trips for a user that is not the OAuth consumer. This is most often done when a travel supplier or TMC needs to create a trip on behalf of a user. The supplier or TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
Cancel a Trip
This endpoint can be used to cancel all segments in a trip. To cancel a trip on behalf of a user, the OAuth access token used to make the API call should be associated with the SAP Concur account of that user. The TripLink supplier or TMC must be registered with SAP Concur and have an SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
Request
POST /travel/trip/v1.1/cancel?tripid=trip_ID[&userid_type=login&userid_value=login_ID]
Path Parameters
| Parameter Name | Data Type | Description |
|---|---|---|
cancel |
required | string |
Request Parameters
| Parameter Name | Data Type | Description |
|---|---|---|
tripid |
string |
Optional: The identifier for the trip to be updated. For example, if the value of tripid is I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL, then the request is POST /travel/trip/v1.1?tripid=I2uwiJJw8r7Owl3IWlSie9WIelxhAhwiL. |
userid_type |
string |
Optional: The type of user identification to use. Possible value is: login_id. |
userid_value |
string |
Optional: The user's login ID. This parameter must be provided in conjunction with the userid_type parameter. The userid_type and userid_value parameters can only be used if the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard. The format for the request URI using the userid_type and userid_value query parameters is /travel/trip/v1.1/trip_ID?userid_type=login&userid_value=login_ID. |
Headers
Authorization Header (Required)
Authorization: OAuth {access_token}
Where access_token is the OAuth 2.0 access token of the user whose trip you want to create or update. If you want to access company-wide itinerary information, the user account associated with the OAuth 2.0 access token must have an SAP Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.
Request Content Body
None.
Cancel Trip Request Schema
The request returns the full trip details for the cancelled trip. If the request is successful, the response trip will not contain any segments because they have been cancelled. The response includes the following additional elements inside the Itinerary parent element:
| Parameter Name | Data Type | Description |
|---|---|---|
id |
string |
The URI including the trip ID. |
ItinLocator |
string |
The itinerary locator value (trip ID without the URL). The ItinLocator value is used when updating an existing trip. |
DateModifiedUtc |
dateTime |
The UTC formatted date that this booking was last modified. |
BookedVia |
string |
The GDS the itinerary was booked in. |
DateBookedLocal |
dateTime |
The date, in the traveler’s local time, that the booking was made. |
Examples
Example: Cancel a Trip with a Specific Trip ID
Request
POST /api/travel/trip/v1.1/cancel?tripId=CNQR1234567890 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...
Response
<Itinerary xmlns="http://www.concursolutions.com/api/travel/trip/2010/06">
<id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
<ItinLocator>CNQR1234567890</ItinLocator>
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<TripName>Trip from Dallas to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-24T23:59:00</EndDateLocal>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<BookedVia>EveryGDS</BookedVia>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
<Bookings>
<Booking>
<Segments/>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>C123456789</RecordLocator>
<BookingSource>ConcurCars</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>TravelSupplier</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
<Booking>
<Segments/>
<Passengers>
<Passenger>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
<RecordLocator>0987654321</RecordLocator>
<BookingSource>ConcurHotel</BookingSource>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<OriginalItinLocator>33491211</OriginalItinLocator>
<ItinSourceName>ConcurTravel</ItinSourceName>
<PassengerCount>1</PassengerCount>
</Booking>
</Bookings>
</Itinerary>
Booking Endpoint
The Booking resource represents booking segments in the SAP Concur Travel system. TripLink suppliers use this resource to display a subset of the full booking fields.
Version
Version 1.1
URI
/travel/booking/v1.1/{query_parameters}
Scope
In order to obtain itinerary data when making Itinerary API calls, the value of the OAuth scope parameter must be set to: ITINER
Create or Update Booking
Creates a new booking or updates an existing booking. A new booking will be assigned to the specified trip, or if no trip is specified, the first itinerary that spans the booking dates. If no trip is specified and no itinerary exists that spans the booking dates, a new itinerary will be created.
This endpoint can be used to create/update bookings for a user that is not the OAuth consumer. This is most often done when a travel supplier or Travel Management Company needs to create/update a booking on behalf of a user. The supplier or TMC must be registered with SAP Concur, and must have an account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
Request
POST /api/travel/booking/v1.0?tripId=12345678 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Request Parameters
Query Parameters - Optional
- tripId={tripId} The unique identifier for the trip. Supplied in order to add a booking to an existing trip.
- userid_type=login_id&userid_value={loginID} The SAP Concur login ID of the user who owns the booking. Only provided when the booking owner is not the OAuth consumer. Can only be used when the OAuth consumer has the required user role.
Examples:
https://www.concursolutions.com/api/travel/booking/v1.1?tripId={tripId}
https://www.concursolutions.com/api/travel/booking/v1.1?userid_type=login_id&userid_value={loginID}
Content Type
application/xml
Authorization Header
Authorization header with OAuth token for a valid SAP Concur user. In order to create or update booking for anyone other than the OAuth consumer, the OAuth consumer must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.
Create or Update Booking Request Schema
The request contains a Booking parent element with the following child elements:
| Required Element | Description |
|---|---|
BookingSource |
The supplier's name. |
RecordLocator |
Record locator for this booking. This is often six alphanumeric characters but can have other formats depending on the booking source |
| Optional Element | Description |
|---|---|
DateBookedLocal |
The date the booking was created, in the booking location's local time. Format: YYYY-MM-DDThh:mm:ss |
FormOfPaymentName |
The name of the form of payment for the booking. |
FormOfPaymentType |
The type of the form of payment. |
TicketMailingAddress |
The mailing address for the booked ticket, if available. |
TicketPickupLocation |
The pickup location for the booked ticket, if available. |
TicketPickupNumber |
The confirmation number to pick up the booked ticket, if available. |
AirfareQuotes |
List of stored airfare quotes for this booking. |
AirlineTickets |
List of Airline Tickets for this booking. |
Charges |
List of Charges for this booking. |
MiscChargeOrders |
List of Miscellaneous AirCharges for this booking. |
Passengers |
The Passengers element contains a Passenger child element for each booked passenger. The description of each child element can be seen in a subsequent table. |
PassPrograms |
List of Pass Programs for this booking. |
PhoneNumbers |
List of Phone numbers associated with this booking. |
RailPayments |
List of Rail payments associated with rail segments in this booking. |
Segments |
List of Segments in this booking. This parent element contains one or more Air, Car, Hotel, Dining, Ride, Rail, Parking, or Event parent elements for the booking. Refer to Booking Object Elements for more information about the child elements contained in the booking elements. |
Delivery |
The method this booking was delivered. |
WaitListSegments |
The segments that the traveler is waitlisted for this booking. |
Warnings |
The warnings associated with the booking. |
WebAddresses |
List of web addresses such as emails, pickup URLs, etc. associated with this bookings |
Passenger Child Elements
| Required Element | Description |
|---|---|
NameFirst |
The first name of the passenger. |
NameLast |
The last name of the passenger. |
| Optional Element | Description |
|---|---|
NameMiddle |
The middle name of the passenger. |
NamePrefix |
The name prefix of the passenger. |
NameRemark |
Additional details about the passenger's name. |
NameSuffix |
The name suffix of the passenger. |
NameTitle |
The title of the passenger. |
TextName |
The user's full name as entered in the booking tool if different from the name in the database. |
FrequentTravelerProgram |
Passenger's loyalty programs |
Response
This function returns the full trip details, as documented in the Response of the Get Itinerary Details function.
If the end user updates an existing reservation which results in a new confirmation number, the old booking must be explicitly cancelled in addition to posting the new booking to SAP Concur. If the previous booking is not cancelled, the user will see both bookings in their SAP Concur trip list.
Examples
Example 1: XML Example Request
POST /api/travel/booking/v1.0?tripId=12345678 HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
...
<Booking xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Segments>
<Car>
<Vendor>AL</Vendor>
<VendorName>Alamo</VendorName>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-23T12:00:00</EndDateLocal>
<StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
<EndDateUtc>2013-12-23T20:00:00</EndDateUtc>
<ConfirmationNumber>F16726AIUS</ConfirmationNumber>
<DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
<DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>A</Transmission>
<AirCondition>R</AirCondition>
<NumPersons>1</NumPersons>
<NumCars>1</NumCars>
<DiscountCode>4321</DiscountCode>
<DailyRate>35.0000</DailyRate>
<TotalRate>105.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
</Car>
</Segments>
<RecordLocator>PANAMA50</RecordLocator>
<BookingSource>Alamo</BookingSource>
<DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
<DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<Passengers>
<Passenger>
<PassengerKey>0</PassengerKey>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
</Booking>
Example 2: XML Example of Successful Response
<Itinerary xmlns="https://www.concursolutions.com/api/travel/trip/2010/06">
<id>https://www.concursolutions.com/api/travel/trip/v1.1/CNQR1234567890</id>
<ItinLocator>CNQR1234567890</ItinLocator>
<ClientLocator>KK-CNQ-1M1P6-5HJ</ClientLocator>
<ItinSourceName>TravelSupplier</ItinSourceName>
<TripName>Trip to Seattle</TripName>
<Comments />
<StartDateLocal>2013-12-21T07:25:00</StartDateLocal>
<EndDateLocal>2013-12-23T23:59:00</EndDateLocal>
<DateModifiedUtc>2012-07-24T19:15:52</DateModifiedUtc>
<BookedVia>EveryGDS</BookedVia>
<BookedByFirstName>Chris</BookedByFirstName>
<BookedByLastName>Miller</BookedByLastName>
<DateBookedLocal>2012-07-24T19:15:52</DateBookedLocal>
<Booking>
<Segments>
<Car>
<Vendor>AL</Vendor>
<VendorName>Alamo</VendorName>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-23T12:00:00</EndDateLocal>
<StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
<EndDateUtc>2013-12-23T20:00:00</EndDateUtc>
<ConfirmationNumber>F16726AIUS</ConfirmationNumber>
<DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
<DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>A</Transmission>
<AirCondition>R</AirCondition>
<NumPersons>1</NumPersons>
<NumCars>1</NumCars>
<DiscountCode>4321</DiscountCode>
<DailyRate>35.0000</DailyRate>
<TotalRate>105.0000</TotalRate>
<RateType>D</RateType>
<Currency>USD</Currency>
</Car>
</Segments>
<RecordLocator>PANAMA50</RecordLocator>
<BookingSource>Alamo</BookingSource>
<DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
<DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
<DateBookedLocal>2013-11-10T13:01:00</DateBookedLocal>
<ItinSourceName>TravelSupplier</ItinSourceName>
<Passengers>
<Passenger>
<PassengerKey>0</PassengerKey>
<NameFirst>Chris</NameFirst>
<NameLast>Miller</NameLast>
</Passenger>
</Passengers>
</Booking>
</Itinerary>
Cancel a Booking
Cancels an existing booking. By default, the OAuth consumer should be the owner of the booking. This endpoint can also be used to cancel bookings that the OAuth consumer does not own. This is most often done when a Travel Management Company needs to cancel bookings on behalf of a user. The TMC must be registered with SAP Concur and have a SAP Concur account that has one of the following user roles: Web Services Administrator for Professional, or Can Administer for Standard.
NOTE:
- Booking records can only be updated by the booking source that created them. SAP Concur verifies the source information before processing the request.
Example:
https://{baseUri}/api/travel/booking/v1.1/cancel?bookingSource={Supplier}&confirmationNumber={confnum}
Request
POST /api/travel/booking/v1.1/cancel?bookingSource={FastTravel}&confirmationNumber={098765431} HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Request Parameters
Query Parameters - Required
- cancel?bookingSource={Supplier}
The cancel keyword and the unique identifier for the supplier, configured by SAP Concur during the application review. The bookingSource must match the Supplier Name associated with the booking.
- confirmationNumber={confnum}
The confirmation number for the booking to cancel.
Example:
https://www.concursolutions.com/api/travel/booking/v1.1/cancel?bookingSource={Supplier}&confirmationNumber={confnum}
Query Parameters - Optional
- userid_type=login_id&userid_value={loginID}
The SAP Concur login ID of the user who owns the booking. Only provided when the booking owner is not the OAuth consumer. Can only be used when the OAuth consumer has the required user role.
Example:
https://www.concursolutions.com/api/travel/booking/v1.1/cancel?bookingSource={Supplier}&confirmationNumber={confnum}&userid_type=login_id&userid_value={loginID}
Content Type
application/xml
Authorization Header
The authorization header must have an OAuth token for valid SAP Concur user. The OAuth consumer must be registered as a Supplier or TMC with SAP Concur, and must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.
Response
This function returns the full booking details, as specified in the Booking Object Elements section.
If the booking is not found, the function returns a HTTP 404 error and the following element:
Status: This element contains the value: NotFound.
Examples
Examples 1: XML Example Request
POST /api/travel/booking/v1.1/cancel?bookingSource={FastTravel}&confirmationNumber={098765431} HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Examples 2: XML Example of Successful Response
<Car>
<Vendor>ZE</Vendor>
<Status>HK</Status>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<EndDateLocal>2013-12-24T12:00:00</EndDateLocal>
<TimeZoneId xsi:nil="true"/>
<StartDateUtc>2013-12-21T20:00:00</StartDateUtc>
<EndDateUtc>2013-12-24T20:00:00</EndDateUtc>
<ConfirmationNumber>0987654321</ConfirmationNumber>
<CancellationNumber>1029384756</CancellationNumber>
<DateCreatedUtc>2012-07-22T11:55:42</DateCreatedUtc>
<DateCancelledUtc>2012-07-25T14:21:35</DateCancelledUtc>
<DateModifiedUtc>2012-07-22T11:55:42</DateModifiedUtc>
<UpgradedDateTime xsi:nil="true"/>
<IsUpgradeAllowed xsi:nil="true"/>
<FrequentTravelerId/>
<StartCityCode>SEA</StartCityCode>
<EndCityCode>SEA</EndCityCode>
<StartLocation>SEA</StartLocation>
<EndLocation>SEA</EndLocation>
<Class>E</Class>
<Body>C</Body>
<Transmission>M</Transmission>
<AirCondition>R</AirCondition>
<PhoneNumber/>
<NumPersons xsi:nil="true"/>
<NumCars>1</NumCars>
<DiscountCode>346660</DiscountCode>
<Charges>
<Fixed>
<Description>Dropoff Fee</Description>
<Currency>USD</Currency>
<Amount>0.0000</Amount>
<StartDateLocal xsi:nil="true"/>
<IsPaid xsi:nil="true"/>
<SemanticsCode>DROPOFFFEE</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
</Fixed>
<RateWithAllowance>
<Currency>USD</Currency>
<Amount>44.0000</Amount>
<StartDateLocal>2013-12-21T12:00:00</StartDateLocal>
<IsPaid xsi:nil="true"/>
<SemanticsCode>DAYS</SemanticsCode>
<SemanticsVendorType>C</SemanticsVendorType>
<PerUnit>DAY</PerUnit>
<NumUnits>1.0000</NumUnits>
<AllowanceUnit/>
<AllowanceNumUnits>250.0000</AllowanceNumUnits>
<AllowanceAmount>0.2400</AllowanceAmount>
<AllowanceIsUnlimited>false</AllowanceIsUnlimited>
</RateWithAllowance>
</Charges>
<Remarks/>
<PerDiemLocation/>
</Car>
See Also
User
Users
The Users resource represents a set of SAP Concur users. It is always managed as a batch of users, even if the batch contains only one user.
- Retrieve a user's information
- Retrieve all users based on search criteria
- Retrieve the list of required fields for creating a user
- Update a user's account information - Create a User is not supported at this time.
- Update a user's password
Version
1.0
Process Flow

Retrieve a User's Information
This resource allows you to get profile information for a given user. If a request URL does not include a ?loginID parameter then the response will be for the logged in user (and you must pass authentication information with your request).
GET api/user/v1.0/user
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
loginID |
string |
- | The URL-encoded SAP Concur login of the user. Optional. |
Get User Response Schema
| Name | Type | Format | Description |
|---|---|---|---|
loginID |
string |
- | The user's login ID. |
Active |
Boolean |
Y/N | Whether the user is currently active. |
FirstName |
string |
- | The user's first name. |
LastName |
string |
- | The user's last name. |
Mi |
string |
- | The user's middle initial. |
EmailAddress |
string |
- | The user's email address. |
EmpId |
string |
- | The unique identifier for the user. |
LedgerName |
string |
- | The user's assigned account code ledger. |
LocaleName |
string |
- | The user's language locale code. One of the Supported Locales. Example: United States English is en_US. |
OrgUnit1 through OrgUnit6 |
string |
- | Varies depending on configuration. |
Custom1 through Custom21 |
string |
- | Varies depending on configuration. If the custom field is a list field, the data will be returned as: (list item short code) list item name. List Field Example: |
CtryCode |
string |
2-character country code | The user's two-digit country code. |
CashAdvanceAccountCode |
string |
- | The user's account code for cash advances. |
CrnCode |
string |
ISO 4217 currency code | The user's three character reimbursement currency. Example: United States Dollar is USD. |
CtrySubCode |
string |
- | The user's two-digit country code and two-digit state or province code. Example: Washington State, United States is US-WA. |
ExpenseUser |
Boolean |
Y/N | Whether the user has access to Expense. |
ExpenseApprover |
Boolean |
Y/N | Whether the user is an Expense approver. |
TripUser |
Boolean |
Y/N | Whether the user has access to Travel. |
InvoiceUser |
Boolean |
Y/N | Whether the user has access to Invoice. |
InvoiceApprover |
Boolean |
Y/N | Whether the user is an Invoice approver. |
ExpenseApproverEmployeeID |
string |
- | The employee ID of the user's Expense approver. If you are importing both a user and their approver, the approver should be listed before the user in the batch. |
IsTestEmp |
Boolean |
Y/N | Whether the user is a test user. |
Retrieve All Users Based on Search Criteria
Note that this is a version 3.0 API and can be found here.
Retrieve the List of Required Fields for Creating a User
Retrieves a list of configured fields on the Global employee form in SAP Concur.
GET api/user/v1.0/FormFields
Required Fields Response Schema
| Name | Type | Format | Description |
|---|---|---|---|
Id |
string |
- | The unique field identifier. |
Label |
string |
- | The displayed field label. |
ControlType |
string |
- | The type of field. |
DataType |
string |
- | The type of data the field collects. |
MaxLength |
string |
- | The maximum length of data in the field. |
Required |
string |
- | Whether the field is required. |
Cols |
string |
- | The number of columns the field occupies. |
Access |
string |
- | The end-user access to the field. |
Width |
string |
- | The width of the field, in pixels. |
Custom |
string |
- | Whether the field is custom. |
Sequence |
string |
- | The sequence of the field on the form. |
These elements are returned for Custom fields only:
| Name | Type | Format | Description |
|---|---|---|---|
ParentFormTypeCode |
string |
- | This element is only populated for multi-level list fields. The type of form that the parent field (the field one level higher in the list hierarchy) is connected to. |
ParentFieldId |
string |
- | The identifier for the field one level higher in the list hierarchy. |
IsCopyDownSourceForOtherForms |
string |
- | Whether the field is used as a copy down source by other forms. |
ListName |
string |
- | The name of the list associated with the field. |
HierLevel |
string |
- | The list level of the field. If it is the second level field in a two-level list, the value would be 2. |
Update a User's Account Information
Updates one or more users. The batch can contain up to 500 users.
NOTE: The User API can be used to add new users, however the user accounts will not be fully configured and ready for use. Additional work to the user profiles must be completed, either with manual edits or updates via the user import, in order to complete the user profiles. There is a high degree of variability in customer configuration that is not all supported by this API. Manual edits or updates via a file import are most likely required to complete the User profiles started with this API. Only POST is supported. Please use the Employee Import feature if the User API does not meet your needs.
POST api/user/v1.0/users
This API requires as its arguments a batch element containing a UserProfile child element for each user to be added (in the future) or updated. The UserProfile child elements will vary depending on the form configuration, and may contain the following elements.
Update User Account Information Request Schema
| Name | Type | Format | Description |
|---|---|---|---|
EmpId |
string |
- | Required. The unique identifier for the user. The default value is the user's email address. Maximum 48 characters. |
FeedRecordNumber |
string |
- | Required. The record number in the current batch. |
LoginId |
string |
- | Required. The user's login ID. The default value is the user's email address. Maximum 128 characters. |
LocaleName |
string |
- | The user's language locale code. List of locale codes are available in the Employee Import Appendix. One of the Supported Locales. Example: United States English is en_US. The supported languages vary by company but always include en_US. Maximum: 5 characters. |
Active |
Boolean |
Y/N | Whether the user is currently active. |
Password |
string |
- | Required. The user's password. This element can be used to enter the password for a new user, but cannot be used to update the password for an existing user. Maximum 255 characters. |
FirstName |
string |
- | The user's first name. Maximum 32 characters. |
LastName |
string |
- | The user's last name. Maximum 32 characters. |
Mi |
string |
- | The user's middle initial. Maximum 1 character. |
EmailAddress |
string |
- | The user's email address. Maximum 255 characters. |
LedgerKey |
string |
- | Required for new users. The user's assigned account code ledger. Example: Default. Maximum 20 characters. |
OrgUnit1 through OrgUnit6 |
string |
- | The custom organizational unit fields on the Employee form. Varies depending on configuration. Use the Employee Form Field resource to get the list of configured fields. Maximum 48 characters for each field. |
Custom1 through Custom21 |
string |
- | The custom fields on the Employee form. Varies depending on configuration. Use the Employee Form Field resource to get the list of configured fields. Maximum 48 characters. |
CtryCode |
string |
ISO 3166-1 alpha-2 country code | Country code, example: United States is US. Maximum 2 characters. |
CashAdvanceAccountCode |
string |
- | The user's account code for cash advances. Maximum 20 characters. |
CrnKey |
string |
ISO 4217 3-letter currency code | Currency code for the user's reimbursement currency. Example: United States Dollar is USD. Maximum 3 characters. |
CtrySubCode |
string |
- | The user's two-character country code and two-character state or province code. Example: Washington State, United States is US-WA. Maximum 2 characters. |
ExpenseUser |
Boolean |
Y/N |
Whether the user has access to Expense. |
ExpenseApprover |
Boolean |
Y/N |
Whether the user is an Expense approver. |
TripUser |
Boolean |
Y/N |
Whether the user has access to Travel. |
InvoiceUser |
Boolean |
Y/N |
Whether the user has access to Invoice. |
InvoiceApprover |
Boolean |
Y/N |
Whether the user is an Invoice approver. |
ExpenseApproverEmployeeID |
string |
- | The employee ID of the user's Expense approver. If you are importing both a user and their approver, the approver should be listed before the user in the batch. Maximum 48 characters. |
NewLoginID |
string |
- | Use this element to change the Login ID for an existing employee. Maximum 128 characters. |
NewEmployeeID |
string |
- | Use this element to change the Employee ID for an existing employee. Maximum 48 characters. |
Update User Account Information Response Schema
| Name | Type | Format | Description |
|---|---|---|---|
records-succeeded |
string |
- | The number of records processed that were successfully added or updated. |
records-failed |
string |
- | The number of records processed that were not successfully added or updated. |
When any users are successfully updated:
The request will return the UserDetails parent element with a UserInfo element for each successfully added or updated user. The UserInfo elements will contain the following child elements:
| Name | Type | Format | Description |
|---|---|---|---|
EmployeeID |
string |
- | The employee ID of the user. |
FeedRecordNumber |
string |
- | The item number of the record in the feed. |
Status |
string |
- | The status of the attempt to add or update the user. Should always contain the word SUCCESS. |
When any users fail:
The request will return the errors parent element with an error parent element for each record failure. The error element will contain the following child elements:
| Name | Type | Format | Description |
|---|---|---|---|
EmployeeID |
string |
- | The employee ID of the user. |
FeedRecordNumber |
string |
- | The item number of the record in the feed. |
Message |
string |
- | The error message. |
Example
<batch xmlns="http://www.concursolutions.com/api/user/2011/02">
<UserProfile>
<LoginID>loginID</LoginID>
<EmployeeID>employeeID</EmployeeID>
<Active>N</Active>
<--! Any more required fields -->
</UserProfile>
</batch>
Update a User's Password
POST api/user/v1.0/Users/password
Updates passwords for up to 500 users.
Update User's Password Request Schema
This function requires as its arguments a UserBatch element containing a User child element for each user. The User element must have the following elements:
| Name | Type | Format | Description |
|---|---|---|---|
LoginID |
string |
- | Required. The user's login ID. The default value is the user's email address. |
Password |
string |
- | The user's new password. |
Update User's Password Response Schema
This request will return a BatchResult parent element with the following child elements:
| Name | Type | Format | Description |
|---|---|---|---|
RecordsSucceeded |
string |
- | The number of records processed that were successfully updated. |
RecordsFailed |
string |
- | The number of records processed that were not successfully updated. |
UserPasswordStatusList |
string |
- | This parent element will contains a UserPasswordStatus element for each user. |
The UserPasswordStatus element contains the following child elements:
| Name | Type | Format | Description |
|---|---|---|---|
LoginID |
string |
- | The login ID of the user. |
Status |
Boolean |
Success/Failed | The status of the attempt to update the user's password. |
Message |
string |
- | Additional details about the success or failure of the request. |
Example
<UserBatch xmlns="http://www.concursolutions.com/api/user/2011/02">
<User>
<LoginID>loginID</LoginID>
<Password>password</Password>
</User>
</UserBatch>
General
HTTP Status Codes
Successful Requests
The web services return a HTTP 2xx response code when the request was successful.
HTTP Success Codes:
| Success Code | Message | Description |
|---|---|---|
| 200 | OK | The request was received successfully. |
Failed Requests
The web service should return a response within 60 seconds. If the request times out without a response, the application should wait for 5 minutes then retry the request.
The web service returns a 4xx or 5xx HTTP response code when there are any errors and will include the following elements:
| Element | Description |
|---|---|
| StatusCode | The HTTP error code. |
| Content | A parent element that contains an Error child element. |
Error elements
| Element | Description |
|---|---|
| Message | The error message. |
| Server-Time | The time the error was generated, based on Concur's server's time zone. |
| Id | The ID of the error within Concur. |
Refer to the individual function documentation for function-specific error formats.
HTTP Error Codes
The full list of possible HTTP error codes can be found here. The table below provides additional details for commonly encountered error codes.
| Error Code | Message | Description |
|---|---|---|
| 400 | Bad Request | This response is returned if any of these conditions is true: * The specified URI is invalid. * The request is not formatted correctly. * The request is missing a required field. * The number of requests received exceed the request limit. * The request encountered a database deadlock. In this case, the developer should resend the request a short time later. * This error can be received if Chunked Transfer-Encoding is enabled by the developer's web server. Concur does not support Chunked Transfer-Encoding. Attendee Web Service: * The batch type parameter is not included on the URI of batch operations. * The request contains 0 attendees. * The request contains over 1000 attendees. Imaging Web Service: * The barcode or reportId is missing. Purchase Order Web Service: * The request contains 0 purchase orders. * The request contains over 1000 purchase orders. List Item Web Service: * The request contains 0 list items. * The request contains over 1000 list items. Payment Batch File: * The Batch ID specified in the URI is invalid. Trip Approval: * The request contains 0 itineraries. User Web Service: * The request contains 0 users. * The request contains over 1000 users. |
| 401 | Unauthorized | The Authorization header is not included in the request. |
| 403 | Forbidden | This response is returned if any of these conditions is true: * The Authorization header is included but it fails validation. This can happen if the OAuth consumer does not have access to the Concur product required by the web service. * The partner application associated with the oauth_consumer_key has not been allowed access to the requested company. * The Oauth token has expired or been revoked. |
| 404 | Not Found | Extract Web Service: The Definition ID or Job ID specified in the URI is invalid. Imaging Web Service: No image was found for the specified report Id or barcode. Itinerary Web Service: The Trip ID or Booking ID specified in the URI is invalid. Payment Batch Web Service: The Batch ID specified in the URI is invalid. |
| 409 | Conflict | Extract Web Service: A job for the specified definition is already queued or running. |
| 500 | Internal Server Error/Not Closed | Expense Report Web Service: This response is returned when the system is unable to calculate an exchange rate for a posted expense report entry. Payment Batch Web Service: The specified batch could not be closed. |
| 503 | Service Unavailable | This response is returned when the web service is down for maintenance. The partner application should sleep for 5 minutes then retry the request. If the request continues to fail after a few retries, the developer should contact concurconnecttech@concur.com. |
Locale Codes
All Concur customers have the following locale set in their entities by default. This is the only locale that is available for all clients.
Default Locale
| Locales | Code |
|---|---|
| English (United States) | en_US |
Customers can request to have additional locales added to their entity if necessary. The following list includes all supported locales.
| All Supported Locales | Code |
|---|---|
| Bulgarian (Bulgaria) | bg_BG |
| Chinese (China) | zh_CN |
| Chinese (Hong Kong) | zh_HK |
| Chinese (Taiwan) | zh_TW |
| Croatian (Croatia) | hr_HR |
| Czech (Czech Republic) | cs_CZ |
| Danish (Denmark) | da_DK |
| Dutch (Belgium) | nl_BE |
| Dutch (Netherlands) | nl_NL |
| English (Australia) | en_AU |
| English (Canada) | en_CA |
| English (India) | en_IN |
| English (Ireland) | en_IE |
| English (New Zealand) | en_NZ |
| English (South Africa) | en_ZA |
| English (United Kingdom) | en_GB |
| English (United States) | en_US |
| Finnish (Finland) | fi_FI |
| French (Belgium) | fr_BE |
| French (Canada) | fr_CA |
| French (France) | fr_FR |
| French (Luxembourg) | fr_LU |
| French (Switzerland) | fr_CH |
| German (Austria) | de_AT |
| German (Germany) | de_DE |
| German (Luxembourg) | de_LU |
| German (Switzerland) | de_CH |
| Hungarian (Hungary) | hu_HU |
| Indonesian (Indonesia) | id_ID |
| Italian (Italy) | it_IT |
| Italian (Switzerland) | it_CH |
| Japanese (Japan) | ja_JP |
| Korean (North Korea) | ko_KP |
| Korean (South Korea) | ko_KR |
| Norwegian (Norway) | no_NO |
| Polish (Poland) | pl_PL |
| Portuguese (Brazil) | pt_BR |
| Romanian (Romania) | ro_RO |
| Russian (Russian Federation) | ru_RU |
| Slovak (Slovakia) | sk_SK |
| Spanish (Argentina) | es_AR |
| Spanish (Bolivia) | es_BO |
| Spanish (Chile) | es_CL |
| Spanish (Colombia) | es_CO |
| Spanish (Costa Rica) | es_CR |
| Spanish (Dominican Republic) | es_DO |
| Spanish (Ecuador) | es_EC |
| Spanish (El Salvador) | es_SV |
| Spanish (Guatemala) | es_GT |
| Spanish (Honduras) | es_HN |
| Spanish (Mexico) | es_MX |
| Spanish (Nicaragua) | es_NI |
| Spanish (Panama) | es_PA |
| Spanish (Paraguay) | es_PY |
| Spanish (Peru) | es_PE |
| Spanish (Puerto Rico) | es_PR |
| Spanish (Spain) | es_ES |
| Spanish (Uruguay) | es_UY |
| Spanish (Venezuela) | es_VE |
| Swedish (Sweden) | sv_SE |
| Thai (Thailand) | th_TH |
| Turkish (Turkey) | tr_TR |
Spend Category Codes
The following table lists Spend Category codes that are used in several of the Concur APIs.
| Code | Name |
|---|---|
| ADVTG | Advertising/Marketing |
| AIRFE | Airline Fee |
| AIRFR | Airfare |
| CARRT | Car Rental |
| COCAR | Company Car - Fixed Expense |
| COCRM | Company Car Mileage |
| COMPU | Computer |
| ENTER | Entertainment |
| FEESD | Fees/Dues |
| GASXX | Gas |
| GOODW | Goodwill |
| GRTRN | Ground Transportation |
| LODGA | Lodging - Track Hotel Spending |
| MEALS | Meal |
| MEETG | Meetings |
| OFFIC | Office |
| OTHER | Other |
| PRCAR | Personal Car - Fixed Expense |
| PRCRM | Personal Car Mileage (Expense Professional), Car Mileage (Expense Standard) |
| PRKNG | Personal Car - Parking Expense |
| RAILX | Rail |
| SHIPG | Shipping |
| SUBSC | Subscription/Publication |
| TELEC | Telecom |
| TRADE | Trade/Convention |
| TRAIN | Training |
Deprecated
SAP Concur Deprecated API List
The following application programming interfaces (APIs) have been deprecated according to the API Lifecycle & Deprecation Policy.
- Attendees v1
- Attendees v1.1
- Attendees v2
- Attendee Types v1
- Authorization (Pre-2017)
- Expense Entry v1.1
- Expense Entry Attendee v2
- Expense Group Configuration v1.1
- Expense Report v1.1
- Expense Report v2
- Direct Connect - Hotel v1
- Imaging v1
- List Item Web Service v1
- Receipts v3
- Request v3
- Travel Web Service v1
- Trip Approval v1
Attendees v1
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
The Shared attendees in the Concur company. Attendees added using this web service are added to the Shared Attendee List (owned by the System and available to all users). This resource can't be used to create attendees on a Private List.
URI
https://www.concursolutions.com/api/expense/attendees/v1.0/
This resource supports the following POST actions:
- Post New Attendee List
- Post Attendee Update List
- Post Attendee Inactivation List
Post new attendee list
Adds one or more attendees. This request creates attendees that are part of the Shared List, which are available to all users. This function requires the attendee resource version 1.0.
Request
Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
| batch | required | The batch keyword. |
| type | required | The type of batch operation to complete. Should be create. |
Example: https://www.concursolutions.com/api/expense/attendee/v1.0/batch?type=create
Headers
- RFC 7235 Authorization - OAuth token for valid Concur user. Required. The OAuth consumer must have one of the following user roles in Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. These roles allow the user to manage data for the entire company.
- RFC 7231 Accept:
application/xml
Payload
This function requires as its arguments an attendee-batch element containing an attendee child element for each attendee to be added. All batch operations allow up to 1000 attendees per batch. If a batch request with over 1000 attendees is sent, only the first 1000 attendees in the batch will be processed.
Response
Headers
- RFC 7231 Content-Type:
application/xml
Payload
Example
Request
POST https://www.concursolutions.com/api/expense/attendee/v1.0/batch?type=create
Authorization: OAuth {access token}
Content-Type: application/xml
<attendee-batch xmlns="http://www.concursolutions.com/api/expense/attendee/2010/05">
<attendee>
<external-id>444543344</external-id>
<type>BUSGUEST</type>
<last-name>Miller</last-name>
<first-name>Chris</first-name>
<company>Len Dev</company>
<currency-code>USD</currency-code>
<custom1>345DERF</custom1>
</attendee>
<attendee>
<external-id>444543345</external-id>
<type>BUSGUEST</type>
<last-name>Davis</last-name>
<first-name>Pat</first-name>
<company>Len Dev</company>
<currency-code>USD</currency-code>
<custom1>345DERK</custom1>
</attendee>
</attendee-batch>
Response
HTTP/1.1 200 OK
Content-Type: application/xml
<attendee-batch-result xmlns="http://www.concursolutions.com/api/expense/attendee/2010/05" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<records-succeeded>1</records-succeeded>
<records-failed>1</records-failed>
<errors>
<error>
<code>1202</code>
<external-id>444543345</external-id>
<message>Missing attendee type</message>
</error>
</errors>
</attendee-batch-result>
Post attendee update list
Updates existing attendees. This request updates attendees that are part of the Shared List, which are available to all users. This function requires the attendee resource version 1.0.
Request
Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
| batch | required | Path: The batch keyword. |
| type | required | Query: The type of batch operation to complete. Should be update. |
Example: https://www.concursolutions.com/api/expense/attendee/v1.0/batch?type=update
Headers
- RFC 7235 Authorization - Authorization header with OAuth token for valid Concur user. Required. The OAuth consumer must have one of the following user roles in Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. These roles allow the user to manage data for the entire company.
- RFC 7231 Accept:
application/xml
Payload
This function requires as its arguments an attendee-batch element containing an attendee child element for each attendee to be updated. All batch operations allow up to 1000 attendees per batch. If a batch request with over 1000 attendees is sent, only the first 1000 attendees in the batch will be processed.
Response
Headers
- RFC 7231 Content-Type:
application/xml
Payload
Example
Request
POST https://www.concursolutions.com/api/expense/attendee/v1.0/batch?type=update
Authorization: OAuth {access token}
Content-Type: application/xml
<attendee-batch xmlns="http://www.concursolutions.com/api/expense/attendee/2010/05">
<attendee>
<external-id>444543344</external-id>
<type>BUSGUEST</type>
<last-name>Miller</last-name>
<first-name>Chris</first-name>
<company>Len Dev</company>
<custom1>345DERL</custom1>
<currency-code>USD</currency-code>
</attendee>
</attendee-batch>
Response
HTTP/1.1 200 OK
Content-Type: application/xml
<attendee-batch-result xmlns="http://www.concursolutions.com/api/expense/attendee/2010/05" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<records-succeeded>1</records-succeeded>
<records-failed>0</records-failed>
</attendee-batch-result>
Post an attendee inactivation list
Uses the update batch type to set existing attendees to Inactive. Attendees will be unavailable for new expense reports but will remain associated with existing expense reports. This function requires the attendee resource version 1.0.
Request
Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
| batch | required | Path: The batch keyword. |
| type | required | Query: The type of batch operation to complete. Should be update. |
Example: https://www.concursolutions.com/api/expense/attendee/v1.0/batch?type=update
Headers
- RFC 7235 Authorization - Authorization header with OAuth token for valid Concur user. Required. The OAuth consumer must have one of the following user roles in Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. These roles allow the user to manage data for the entire company.
- RFC 7231 Accept:
application/xml
Payload
This function requires as its arguments an attendee-batch element containing an attendee - inactive child element for each attendee to be inactivated. All batch operations allow up to 1000 attendees per batch. If a batch request with over 1000 attendees is sent, only the first 1000 attendees in the batch will be processed.
Response
Headers
- RFC 7231 Content-Type:
application/xml
Payload
Example
Request
POST https://www.concursolutions.com/api/expense/attendee/v1.0/batch?type=update HTTP/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
<attendee-batch xmlns="http://www.concursolutions.com/api/expense/attendee/2010/05">
<attendee>
<external-id>444543344</external-id>
<inactive>true</inactive>
</attendee>
</attendee-batch>
Response
HTTP/1.1 200 OK
Content-Type: application/xml
<attendee-batch-result xmlns="http://www.concursolutions.com/api/expense/attendee/2010/05" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<records-succeeded>1</records-succeeded>
<records-failed>0</records-failed>
</attendee-batch-result>
Schema
NOTE: The element names are case-sensitive.
Attendee
| Element | Required/Optional | Description |
|---|---|---|
| external-id | required | This is the unique identifier for the attendee from the external (to Concur) system. Maximum 48 characters. |
| type | required | The attendee type code. Refer to the Attendee Types v3 documentation. Maximum 8 characters. |
| last-name | required | The last name of the attendee. Maximum 132 characters. |
| first-name | optional | The first name of the attendee. Maximum 50 characters. |
| company | optional | The name of the attendee’s company. Maximum 150 characters. |
| title | optional | The attendee's title. Maximum 32 characters. |
| total-amount-ytd | optional | The year to date total amount for the attendee. This sets the starting value for year to date attendee spend amount calculations. |
| currency-code | required, if total-amount-ytd is supplied | Defines the currency to be used when totaling costs for the attendee. Must be a 3-letter ISO 4217 currency code for the currency. Maximum 3 characters. |
| customx | required, if the field is required on the Attendee form | There can be one element for each custom field that is configured on the attendee form. There are 20 possible custom fields for attendee forms. The numbering matches the Concur custom field numbering and is not necessarily sequential. If the attendee form has custom 1, custom 3 and custom 10 on it, the custom1, custom3, and custom10 elements should be included. Concur Expense is vastly configurable. Use the following process to get the list of custom fields configured for the Attendee form: 1. Use the Get Available Form Types function to get the code associated with the Attendee Detail View form. 2. Use the Get Form Data function to get the FormId for the specific attendee form that you wish to use. 3. Use the Get Form Field Details function to get the list of configured fields (including custom fields) for the attendee form. Maximum 100 characters. |
Attendee - Inactive
| Element | Required/Optional | Description |
|---|---|---|
| external-id | required | This is the unique identifier for the attendee from the external (to Concur) system. Maximum 48 characters. |
| inactive | required | This is set to true to inactivate the attendee. Format: true/false |
Attendee Batch Result
| Element | Description |
|---|---|
| records-succeeded | The number of records processed successfully. |
| records-failed | The number of records processed which failed. |
| errors | An error parent element for each record failure. |
Error
| Element | Description |
|---|---|
| code | The code associated with the error. |
| external-id | The external ID of the record that failed. |
| message | The error message. |
Attendees v2
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
Description
The attendees in the Concur company. This resource can be used to retrieve attendee information for any attendee in the Concur company, regardless of whether they are Private or Shared. In future releases, this resource will be enhanced to provide full attendee management functionality.
This API allows developers to manage attendees in Concur. The Attendee resource can be used to retrieve attendee information for private or shared attendees. In future releases, the Attendee resource will be updated with additional functionality for managing all attendees in Concur.
The Attendee resource manages attendees in batches, and can be used to add, update or inactivate attendees. This resource provides functionality similar to the Attendee List Import in Concur. Attendees added using this resource are added to the Shared Attendee List (owned by the system and available to all users).
Product Restrictions
Concur products are highly configurable, and not all clients will have access to all features.
Partner developers must determine which configurations are required for their solution prior to the review process.
Existing clients can work with Concur Advantage Technical Services to create custom applications that work with their configuration.
See also
URI
https://www.concursolutions.com/api/expense/v2.0/attendees
Resources
Get attendees
Retrieves the attendees matching the specified search criteria. Developers can specify one or more External IDs or the Attendee ID to search the Expense database.
Request
Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
| attendeeID | optional | Path: The unique identifier for the attendee in Concur. This information is returned in the AttendeeID element of the response of the Get Report Details function. |
| externalid | optional | Query: The unique identifier for the attendee outside of Concur. This information is returned in the ExternalID element of the response of the Get Report Details function. Up to 10 external IDs can be supplied in a comma separated list. |
Examples:
https://www.concursolutions.com/api/expense/v2.0/attendees/{attendeeID}
https://www.concursolutions.com/apiexpense/v2.0/attendees?externalid={externalID}
https://www.concursolutions.com/apiexpense/v2.0/attendees?externalid={externalID1},{externalID2},{externalID3}
Headers
- RFC 7235 Authorization - Authorization header with OAuth 2.0 access token for a Concur user. Required. To manage data for an entire company, the Concur account associated with the access token must have one of these roles:
- Web Services Administrator for Professional
- Can Administer for Standard.
- RFC 7231 Content-Type:
application/xmlorapplication/json
Get Attendee Details Response
Content Types
- application/json
- application/xml
Content Body
This request will return an Attendees parent element containing an Attendee child element for each attendee.
Attendee elements
| Element | Description |
|---|---|
| AttendeeType | The type of attendee. Maximum 40 characters. |
| FirstName | The attendee's first name. Maximum 50 characters. |
| LastName | The attendee's last name. Maximum 132 characters. |
| Company | The attendee's company name. Maximum 150 characters. |
| Title | The attendee's title. Maximum 32 characters. |
| ExternalID | The unique identifier for the attendee, managed outside Concur. Maximum 48 characters. |
| Custom1 through Custom20 | The details from the Custom fields. These may not have data, depending on configuration. For information about the child elements of this parent element, see the Custom child elements table below. |
| HasExceptionsPrevYear | Whether the attendee has exceptions in the previous year, based on yearly total limits for attendees. Maximum 1 character. Format: Y/N |
| HasExceptionsYTD | Whether the attendee has exceptions in the current year, based on yearly total limits for attendees. Maximum 1 character. Format: Y/N |
| IsDeleted | Whether the attendee is marked as deleted. Maximum 1 character. Format: Y/N |
| OwnerEmpName | The name of the employee that owns the attendee record. |
| TotalAmountPrevYear | The total amount spent on the attendee in the previous calendar year. |
| TotalAmountYTD | The total amount spent on the attendee in the current calendar year. |
| VersionNumber | The attendee's version number. |
| AttendeeID | Attendee unique identifier within Concur. |
| AttendeeTypeCode | The unique identifier for the attendee type. |
| AttendeeOwnerID | The unique identifier for the person or system that owns the attendee. |
| CurrencyCode | The 3-letter ISO 4217 currency code for attendee related amounts. |
Custom elements
| Element | Description |
|---|---|
| Type | The custom field type. Will be one of the following: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text. |
| Value | The value in the custom field. Maximum 100 characters. |
| Code | Custom list fields will include the list item code in this element. |
Examples
XML Example Request with Attendee ID
GET https://www.concursolutions.com/api/expense/v2.0/attendees/nFaAj0ncBsvkgnPMY5QWfBbbWyv$sQh2oW
Authorization: OAuth {token}
XML Example Request with External ID
GET https://www.concursolutions.com/api/expense/v2.0/attendees?externalid=234567
Authorization: OAuth {token}
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
<Attendees xmlns="http://www.concursolutions.com/api/expense/expensereport/2012/07" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Attendee>
<AttendeeType>BUSGUEST</AttendeeType>
<FirstName>Chris</FirstName>
<LastName>Miller</LastName>
<Company />
<Title />
<ExternalID>234567</ExternalID>
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<HasExceptionsPrevYear>N</HasExceptionsPrevYear>
<HasExceptionsYTD>N</HasExceptionsYTD>
<IsDeleted>N</IsDeleted>
<OwnerEmpName>Davis, Pat</OwnerEmpName>
<TotalAmountPrevYear>0.00000000</TotalAmountPrevYear>
<TotalAmountYTD>0.00000000</TotalAmountYTD>
<VersionNumber>1</VersionNumber>
<AttendeeID>nFaAj0ncBsvkgnPMY5QWfBbbWyv$sQh2oW</AttendeeID>
<AttendeeTypeCode>BUSGUEST</AttendeeTypeCode>
<AttendeeOwnerID>pd123456</AttendeeOwnerID>
<CurrencyCode>USD</CurrencyCode>
</Attendee>
</Attendees>
Responses and Errors
Refer to the HTTP Codes page for details of the common responses and errors.
Attendee List Errors
The web service will not return a 4xx HTTP response code for a batch operation even when every item in the batch failed to be created or updated. The client must inspect the response to look for warnings or errors with individual batch items.
When there are errors with batch items, the first ten errors are returned in the <errors> element in the request response, which includes their error code, the item that caused the error, and the error message. Any additional error messages are truncated. This prevents a large volume of error data in the event of a formatting mistake.
XML Response Error Codes
| Error Code | Message |
|---|---|
| 1101 | Could not find attendee-batch element. |
| 1102 | Error parsing attendee record X |
| 1201 | Missing external id for attendee record X |
| 1202 | Missing attendee type |
| 1203 | Missing currency code |
| 1204 | External id too long |
| 1205 | Attendee type too long |
| 1206 | Invalid inactive value. |
| 1207 | Attendee of type NOSHOWS ignored. |
| 1208 | Invalid currency code |
| 1209 | Missing required field X |
| 1210 | Invalid time stamp for field X |
| 1211 | Invalid money or money value for field X |
| 1212 | Invalid money or numeric value for field X |
| 1213 | Invalid integer for field X |
| 1214 | Invalid boolean value for field X |
| 1215 | Invalid char value for field X |
| 1216 | Invalid varchar value for field X |
| 1217 | Value too long for field X |
| 1218 | Invalid attendee type |
| 1219 | More than one value was specified for the X field in record X |
| 1221 | Invalid code for field X |
| 1222 | Missing code for field X |
| 1301 | Unexpected error creating attendee |
| 1302 | Unexpected error updating attendee |
| 1303 | Unexpected error getting attendee type list |
| 1304 | Unexpected error processing batch request. |
| 1305 | Cannot update the attendee data for a non existing attendee. |
Attendee Types v1
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
Description
The Attendee Type resource represents the type of attendee as configured in Concur. Retrieves the list of attendee types for the company.
Version
1.0
URI
https://www.concursolutions.com/api/expense/attendee/v1.0/type
Get list of attendee types
Request
Parameters
None.
Headers
- RFC 7231 Content-Type:
application/xml - RFC 7235 Authorization
- The authorization header must have an OAuth token for a valid Concur user.
- The OAuth consumer must have one of the following user roles in Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. These roles allow the user to manage data for the entire company.
Response
Payload
This response will return an attendee-types parent element containing an attendee-type child element for each attendee type.
| Element | Description |
|---|---|
| type | The attendee type code. |
| name | The attendee type name. |
Example
Request
GET https://www.concursolutions.com/api/expense/attendee/v1.0/type
Authorization: OAuth {access token}
Response
HTTP/1.1 200 OK
Content-Type: application/xml
<attendee-types xmlns="http://www.concursolutions.com/api/expense/attendee/2010/05" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<attendee-type>
<type>BUSGUEST</type>
<name>Business Guest</name>
</attendee-type>
<attendee-type>
<type>EMPLOYEE</type>
<name>Employee</name>
</attendee-type>
</attendee-types>
Related
Pre-2017 Authorization (Deprecated)
Authentication
This API has been deprecated.
Deprecation Date: 02/04/2017
If you are a new partner or an existing one creating a new app, please refer to the new authentication version documentation.
Please contact your Partner Enablement representative before starting any new development to ensure a smooth and successful certification process.
Pre-2017 Authorization - Access tokens
An access token is a long-lived token used to make API calls.
Verb and URIs
All authentication and authorization tasks use the GET verb and URI as noted here depending on type of application:
| Type | Verb + URI |
|---|---|
| Native | GET https://{InstanceURL}/net2/oauth2/accesstoken.ashx |
| Web or Auto-Connect | GET https://{InstanceURL}/net2/oauth2/GetAccessToken.ashx |
Keys and Secrets
The Application Authorization section in the New Partner Application page includes Key and Secret fields that are used to generate a request token which is later exchanged for an access token.
| Field | URI Parameter | Description |
|---|---|---|
Key |
client_id |
Unique identifier for the application. |
Secret |
client_secret |
Unique value for the application. |
Getting an access token
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
code |
string |
{request_token} |
Required The request token. |
client_id |
string |
{key} |
Required The application key. |
client_secret |
string |
{secret} |
Required The application secret. |
Input
None
Response
Refreshing an access token
NOTE: The token being refreshed must be used to make the refresh call.
| Verb + URI |
|---|
GET https://{InstanceURL}/net2/oauth2/getaccesstoken.ashx?refresh_token={your refresh token}&client_id={your_client_id}&client_secret={your_client_secret} |
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
refresh_token |
string |
Refresh_Token |
Required The refresh token. |
client_id |
string |
{key} |
Required The application key. |
client_secret |
string |
{secret} |
Required The application secret. |
Input
None
Response
| Name | Type | Format | Description |
|---|---|---|---|
| Instance_URL | string |
- | Identifies the Concur datacenter where the user's data resides. For example, if the Instance_Url is https://www.ea1.concursolutions.com, then all API calls for this user should use this URL as a prefix in subsequent API calls |
| Token | string |
- | The access token value passed in the Authorization header when making API calls. It is a long-lived token which is currently set to expire after one year from creation. You should securely store the token and use it for all subsequent API requests until the token expires. Before it does, you should send a request to refresh the token prior to the expiration date. |
| Expiration_Date | string |
- | The Universal Coordinated Time (UTC) date and time when the access token expires. |
Revoking a single access token for a given user
POST https://{InstanceURL}/net2/oauth2/revoketoken.ashx
Note: To revoke tokens, the caller must have one of the following roles:
Web Services Administratorfor Concur Professional/PremiumCan Administratorfor Concur Standard.
Headers
| Header | Format | Description |
|---|---|---|
Authorization |
https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.8. | OAuth {access_token} of user with proper role. |
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
token |
string |
{access_token} |
Required The token to be revoked. |
Response
None
Example
POST https://www.concursolutions.com/net2/oauth2/revoketoken.ashx?token=fdjhk2382kwkajsklwe8i3932kslswl Authorization: OAuth fdjhk2382kwkajsklwe8i3932kslswl
Revoking all access tokens for a user
POST https://www.concursolutions.com/net2/oauth2/revoketoken.ashx
Headers
| Header | Format | Description |
|---|---|---|
Authorization |
https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.8. | OAuth {access_token} of user with proper role. |
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
consumerKey |
string |
{key} |
Required The key of the application. |
user |
string |
{user_LoginID} |
Required The LoginID of the user. |
Response
w None
Example
POST https://www.concursolutions.com/net2/oauth2/revoketoken.ashx?consumerKey=eZByXv2X41cJlC21pSVvRi&user=Maria Authorization: OAuth fdjhk2382kwkajsklwe8i3932kslswl
Choosing an authorization flow
Use this table to decide which OAuth 2.0 authorization flow to use for the application:
| If you need to... | Use this flow |
|---|---|
| Get an access token for prototyping, designing and testing an application. | Native |
| Get an access token for a user with the Web Services Administrator role and don't require the user to assent (usually for back-office integration apps). | Native |
| Inform the end-user how the app will access their data. | Web or App Center |
| Have an end-user-facing app and wish to initiate the account linking from the app, outside of the Concur App Center. NOTE: These apps must also support App Center Flow so your app is available in the Mobile App Center. Most end-user apps will be used predominantly on a mobile device. | Web |
| Distribute the app in the Mobile App Center | App Center |
| Distribute the app in the App Center and are not a TripLink supplier. | App Center |
| Distribute the app in the App Center and are a TripLink supplier. | Auto-Connect |
Native
The request must contain the following HTTP headers:
Headers
| Header | Format | Description |
|---|---|---|
Authorization |
https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.8. | The Base-64 encoded Concur credentials (LoginID:Password) of the user requesting access in the HTTP Basic Authentication format. If no password is used, the user name must still end with a colon. |
X-ConsumerKey |
{key} |
Unique identifier for the application. |
Example
GET {uri} Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== X-ConsumerKey: hj7683jslks93lalkjss93
Response
Web
There are two types of access levels that can be enabled with web flow:
| Type | Description |
|---|---|
| Company Level | A company can enable an application to use their data in Concur. |
| User Level | A user can enable apps to use their individual data. |
This is determined by the type of Concur user account used in the process.
The web flow is as follows:
- Application redirection to the Concur website for authentication and authorization.
- Parse of a inbound HTTP request from the Concur system to an application specified endpoint.
- Getting an access token
Application Redirection to the Concur website for authentication and authorization.
https://www.concursolutions.com/net2/oauth2/Login.aspx?{parameters}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
client_id |
string |
{key} |
Required The application key. |
scope |
string |
{scope} |
The comma separated list of APIs for which authorization will be granted. |
redirect_uri |
string |
- | The URI of the partner application where Concur will redirect the user after authentication and access approval. |
state |
string |
- | Optional partner application-defined state variable. This variable is specified by the partner application and will be returned intact by the Concur's OAuth provider when the user is redirected to the redirect URL. Values are generally passed in this parameter when the state of the value cannot be maintained by the partner application, for instance when making calls between multiple, disparate web pages. Example: The state variable can contain the ID of the user in the partner application, so that the token returned in the callback can be associated to the specified user and subsequently saved in the database of the partner application. |
Parse of a inbound HTTP request from the Concur system to an application specified endpoint.
http://{redirect_uri}?{parameters}
- If access is denied the
erroranderror_descriptionparameters are used. - If access is granted the
codeparameter is used.
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
error |
string |
- | The name of the error. |
error_description |
string |
- | Description of the error. |
code |
string |
{request_token} |
The request token. |
AppCenter
The AppCenter flow is as follows:
- Listening for an HTTP GET request from the Concur system.
- The listener must be hosted at the URI specified in the App Center listing.
- The request will be in this form:
GET {listener_URI}?code={request_token}
- Parsing the request token value from the
codequery parameter. - Getting an access token
Auto-Connect
The Auto-Connect flow is an authorization to support Connection Requests API calls from TripLink applications. During the Auto-Connect flow, the request token associated with a TripLink application is exchanged for an access token for the user who granted the TripLink application access to the user's Concur data.
Periodically getting a list of connection requests.
GET /common/connectionrequestsFor each user in the connection requests response: Getting an access token
For each connection request, call any other Concur APIs you need to match the Concur user with the user in your system. When the user is successfully matched, or when matching fails, update the connection request.
PUT /common/connectionrequests/{id}If you encounter an error that makes it impossible to complete the connection process, revoke the access token so the user knows that the connection attempt failed and they can try again at a later time.
Expense Entry Itemization v1.1
This API has been deprecated.
Deprecation Date: 05/19/2016
Unsupported Date: 11/19/2016
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
Expense Entry Itemizations are children of an expense entry that subdivide the expense. A common use case for itemizations is on a hotel bill, which can have separate itemizations for room rate, room tax, and services such as laundry or minibar.
URI
https://www.concursolutions.com/api/expense/expensereport/v1.1/report/{reportId}/entry/{entryId}/itemization/{itemizationId}
POST Expense Entry Itemization
Creates or updates an itemization record for the specified expense entry.
NOTE: Posting expense report information is a multi-stage process. Refer to the Processes section of the Expense Report Web Service page for the steps required to post new expense reports and entries.
Request
Request parameters
Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
{_reportId_} |
Required | The unique identifier for the expense report. |
{_entryId_}/Itemization |
Required | The unique identifier for the expense entry and the Itemization keyword. |
{_itemizationID_} |
Optional | The unique identifier for the itemization. |
Examples:
https://www.concursolutions.com/api/expense/expensereport/v1.1/report/{reportId}/entry/{entryId}/itemization
https://www.concursolutions.com/api/expense/expensereport/v1.1/report/{reportId}/entry/{entryId}/itemization/{itemizationId}
URI Sources
- The reportId value is returned by the Get List of Reports function, and as part of the Report-Details-Url element of the Post Expense Report Header function.
- The entryId value is returned in the RpeKey element of the Get Report Details function.
- The itemizationId is returned as part of the Itemization-Url value returned by this function.
Headers
- Authorization header with OAuth token for valid Concur user. Required.
The OAuth Consumer must have one of the following roles to post itemizations for expenses in reports that they do not own: Web Services Admin for Professional, or Can Administer for Standard.
Content-Type header
application/xml
Payload
This request contains an ExpenseItemizations parent element with an Itemization parent element for each included itemization. The Itemization parent element has the following child elements.
Itemization elements
| Element | Required (must contain value)? | Description |
|---|---|---|
| ExpKey | Y | The expense type key for the expense. Expense Type Keys are returned in the ExpKey element by the Get Expense Group Configuration endpoint. The expense type key cannot be modified when updating expense entries. |
| Description | Depends on configuration | The description for the expense. |
| TransactionAmount | Y | The total amount of the itemization in the original currency, with up to three decimal places. Example: 123.654 |
| PostedAmount | Depends on configuration | The amount of the itemization in the user's reimbursement currency, with up to three decimal places. Example: 123.654. May vary from transaction amount if some of the expense is marked personal or if it has been converted to another currency. See Notes for more information. |
| Custom1 through Custom20 | Depends on configuration | The Expense Entry Form custom fields. Itemizations are child entries to the expense entry, and they share the custom fields. May be required depending on configuration. Refer to the Processes, Post Expense Report Data section of Expense Report for the steps necessary to gather required field information. NOTE: If any of the custom fields are configured to contain list values, please refer to the Posting Custom List Items page for information on how to correctly submit list item values. |
| IsPersonal | N | Whether the expense entry is a personal expense. Personal expenses are not reimbursed in Concur Expense. Personal expenses cannot be itemized. Format: N |
| Comment | Depends on configuration | The itemization comment. |
NOTES:
- The update request must include the ExpKey and TransactionAmount fields. All other fields only need to be included if they were updated.
- Update requests cannot change the ExpKey for an existing entry.
- When handling foreign currency transactions, the CrnCode and TransactionAmount values should indicate the original transaction amount and currency. The PostedAmount value should contain the transaction amount converted into the posting currency (the user's reimbursement currency). Concur will calculate the exchange rate for the expense based on these two fields.
Response
Payload
This request will return an ItemizationStatusList parent element with an ItemizationStatus child element for each posted itemization. The ItemizationStatus element will contain the following child elements.
ItemizationStatus elements
| Element | Description |
|---|---|
| Index | The entry's sequence in the request. |
| Status | The status of the request. Possible values are: 200: The itemization was successfully saved. 400: The Request includes an error such as a syntax error or missing required element. 404: The Itemization URI is in the correct syntax, but the system can't find the itemization. It may have been deleted from the system. 500: The request has the correct syntax and refers to an existing itemization, but the system was unable to save due to a system conflict. |
| Itemization-Url | The URI to get the itemization details. |
Examples
XML example request
POST https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nxxKgLlnROz$sQ6SKJFjLNs4OWBErcJ8yX/entry/nE0avYnILNNi9qkVyS3lYPuv4Mop4QmVs/Itemization HTTP/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
<ExpenseItemizations xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03">
<Itemization>
<ExpKey>DINNR</ExpKey>
<Description>Dinner</Description>
<TransactionAmount>56.00</TransactionAmount>
<PostedAmount>56.00</PostedAmount>
<Comment>Dinner</Comment>
<Custom1>Dinner</Custom1>
<Custom2>Room Service</Custom2>
<Custom5>Too late for restaurant</Custom5>
<IsPersonal>N</IsPersonal>
</Itemization>
<Itemization>
<ExpKey>LUNCH</ExpKey>
<Description>Lunch</Description>
<TransactionAmount>24.64</TransactionAmount>
<PostedAmount>24.64</PostedAmount>
<Comment>Lunch</Comment>
<IsPersonal>N</IsPersonal>
</Itemization>
<Itemization>
<ExpKey>BRKFT</ExpKey>
<Description>BreakFast</Description>
<TransactionAmount>15.34</TransactionAmount>
<PostedAmount>15.34</PostedAmount>
<Comment>Breakfast</Comment>
<IsPersonal>N</IsPersonal>
</Itemization>
</ExpenseItemizations>
XML example response
HTTP/1.1 200 OK
Content-Type: application/xml
<ItemizationStatusList xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ItemizationStatus>
<Index>1</Index>
<Status>SUCCESS</Status>
<ItemizedEntry-Details-Url>https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nxxKgLlnROz3zHJBCRk$puJLmXp25RsAwp/entry/nE0avYnILNNi9qkVyS3lYPuv4Mop4QmVs/itemization/nE0avYnILN69JgpJGuSCy5qqirEfFcds4</ItemizedEntry-Details-Url>
</ItemizationStatus>
<ItemizationStatus>
<Index>2</Index>
<Status>SUCCESS</Status>
<ItemizedEntry-Details-Url>https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nxxKgLlnROz3zHJBCRk$puJLmXp25RsAwp/entry/nE0avYnILNNi9qkVyS3lYPuv4Mop4QmVs/itemization/nE0avYnILN65lGE4Zka1YOp608re6ASJb</ItemizedEntry-Details-Url>
</ItemizationStatus>
<ItemizationStatus>
<Index>3</Index>
<Status>SUCCESS</Status>
<ItemizedEntry-Details-Url>https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nxxKgLlnROz3zHJBCRk$puJLmXp25RsAwp/entry/nE0avYnILNNi9qkVyS3lYPuv4Mop4QmVs/itemization/nE0avYnILN6nw6Hi0jhAuYXAXiXNej7zb</ItemizedEntry-Details-Url>
</ItemizationStatus>
</ItemizationStatusList>
Expense Entry v1.1
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
An expense entry in an expense report.
NOTE: You can find version 3.0 here
URI
https://www.concursolutions.com/api/expense/expensereport/v1.1/report/{reportId}/entry/{entryId}
Get Expense Entry Details Request
Retrieves the details for the specified expense entry
Supported Accept Types
application/xml
Parameters
| Query Parameter | Description |
|---|---|
{_reportId_} |
Reqired The unique identifier for the expense report. |
{_entryId_} |
The unique identifier for the expense entry. |
Request Headers
- Authorization header with OAuth token for valid Concur user.
XML Example Request
GET https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nxxKgLlnROz3zHJBCRksaas23dsfs/entry/n7We3qWw99u1KoWTMaLhSC$pXBYzQ1UDhn HTTP/1.1
Authorization: OAuth {access token}
Response
This request will return an ExpenseEntry parent element with the following child elements:
| Element | Description |
|---|---|
| ApprovedAmount | The approved amount of the entry in the user's reimbursement currency. The Get Report Details function returns the report currency, which is the user's reimbursement currency, in the CrnCode element. |
| Attendee-Url | The URL to the attendees list for the entry. |
| Allocation-Url | The URL to the allocations list for the entry. |
| BusinessPurpose | The business purpose field from the report header. |
| EreceiptId | The ID for the attached e-receipt, if available. |
| ExchangeRate | The exchange rate that applies to the entry. |
| ExpenseKey | The expense type key for the entry. Use the Get Expense Group Configuration endpoint to get the full list of expense types. |
| ExpenseName | The expense type for the entry. |
| SpendCategory | The spend category specified for this expense type. Varies by client, used in reporting. |
| HasAllocation | Defines the amount of allocations for the expense. Possible values are: P, for partial allocation, F, for full allocation, or N, for no allocation. |
| HasAttendees | Whether the expense has attendees. |
| HasComments | Whether the expense has comments. |
| HasExceptions | Whether the expense has exceptions. |
| HasVat | Whether the expense has VAT data. |
| ImageRequired | Whether a receipt image is required for the entry. |
| IsCreditCardCharge | Whether the expense came from a credit card feed. |
| IsItemized | Whether the expense has itemizations. |
| Itemizations-Url | The URL to the itemization list. |
| IsPersonal | Whether the expense is personal. |
| IsPersonalCardCharge | Whether the expense came from a personal card feed. |
| LastModified | The UTC date when the entry was last modified. |
| LocationName | The location for the expense entry, usually the city name. |
| OrgUnit1 through OrgUnit6 | The details from the Org Unit custom fields. These may not have data, depending on configuration. |
| PaymentTypeKey | The key for the payment type for the entry. Use the Get Expense Group Configuration function to map the payment type key to the payment type name. |
| PostedAmount | The amount of the expense entry in the user's reimbursement currency. The Get Report Details function returns the report currency, which is the user's reimbursement currency, in the CrnCode element. |
| ReceiptImageId | The ID for the receipt image attached to the entry. |
| ReceiptRequired | Whether the original receipt is required for the entry. |
| ReportEntryID | The ID of the report entry. |
| ReportID | The unique key of the report the entry is in. |
| TransactionAmount | The amount of the expense entry in the original transaction currency. |
| TransactionCurrencyName | The currency name of the expense entry transaction amount. |
| TransactionDate | The date of the expense entry. |
| VendorDescription | The vendor name of the expense entry, which can be entered manually by the user or imported from the card transaction Merchant Name field. |
| X_UserID | The user ID associated with the entry. |
| Custom1 through Custom40 | The details from the Custom fields. These may not have data, depending on configuration. If the custom field is a list field, the data will be returned as: (list item short code) list item name. List Field Example: |
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
<ExpenseEntry xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ApprovedAmount>40.00000000</ApprovedAmount>
<Attendee-Url>https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nYO0ck05r5fATbnjrMBf0d$sCIBqX8WQYw/entry/nbmTPob9qSUJWKttTEr6MLaXaPKYYPv7U/Attendees
</Attendee-Url>
<Allocation-Url>https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nYO0ck05r5fATbnjrMBf0d$sCIBqX8WQYw/entry/nbmTPob9qSUJWKttTEr6MLaXaPKYYPv7U/Allocations</Allocation-Url>
<BusinessPurpose />
<EreceiptId />
<ExchangeRate>1.00000000000000</ExchangeRate>
<ExpenseKey>BUSML</ExpenseKey>
<ExpenseName>OTHER</ExpenseName>
<SpendCategory>Miscellaneous</SpendCategory>
<HasAllocation>N</HasAllocation>
<HasAttendees>Y</HasAttendees>
<HasComments>N</HasComments>
<HasExceptions>N</HasExceptions>
<HasVat>N</HasVat>
<ImageRequired>N</ImageRequired>
<IsCreditCardCharge>N</IsCreditCardCharge>
<IsItemized>N</IsItemized>
<Itemizations-Url>https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nYO0ck05r5fATbnjrMBf0d$sCIBqX8WQYw/entry/nbmTPob9qSUJWKttTEr6MLaXaPKYYPv7U/Itemization</Itemizations-Url>
<IsPersonal>N</IsPersonal>
<IsPersonalCardCharge>N</IsPersonalCardCharge>
<LastModified>2011-06-18T16:03:31</LastModified>
<LocationName />
<PaymentTypeKey>CASH</PaymentTypeKey>
<PostedAmount>40.00000000</PostedAmount>
<ReceiptImageId />
<ReceiptRequired>N</ReceiptRequired>
<ReportEntryID>nbmTPob9qSUJWKttTEr6MLaXaPKYYPv7U</ReportEntryID>
<ReportID>nYO0ck05r5fATbnjrMBf0d$sCIBqX8WQYw</ReportID>
<TransactionAmount>40.00000000</TransactionAmount>
<TransactionCurrencyName>US, Dollar</TransactionCurrencyName>
<TransactionDate>2011-06-15T00:00:00</TransactionDate>
<VendorDescription />
<X_UserID>cmiller@example.com</X_UserID>
<OrgUnit1 />
<OrgUnit2 />
<OrgUnit3 />
<OrgUnit4 />
<OrgUnit5 />
<OrgUnit6 />
<Custom1>Value</Custom1>
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<Custom21 />
<Custom22 />
<Custom23 />
<Custom24 />
<Custom25 />
<Custom26 />
<Custom27 />
<Custom28 />
<Custom29 />
<Custom30 />
<Custom31 />
<Custom32 />
<Custom33 />
<Custom34 />
<Custom35 />
<Custom36 />
<Custom37 />
<Custom38 />
<Custom39 />
<Custom40 />
</ExpenseEntry>
Post Expense Entry Request
Posts an expense report entry for the specified report. Use the Post Expense Report Header function to create the report, then use this endpoint to create the expense line items. You can update existing expense entries using this endpoint.
NOTE: Posting new expense reports is a multi-stage process. Refer to the Processes section of the Expense Report Web Service page for the steps required to post new expense reports and entries.
NOTE: Concur recommends that you post one expense entry per request. Future versions of this endpoint will require this behavior.
Supported Content Types
application/xml
Parameters
| Query Parameters - Required | Query Parameters - Optional |
|---|---|
{_reportId_}/entry |
Required The unique identifier for the expense report and the entry keyword. Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/_{reportId}_/entry. URI Source: The reportId value is returned in the ReportID element by the Get List of Reports function, and as part of the Report-Details-Url element of the Post Expense Report Header function. |
{_entryId_} |
The unique identifier for the expense entry. Example: https://www.concursolutions.com/api/expense/expensereport/v1.1/report/_{reportId}_/entry/{_entryId_}. URI Source: The entryId value is returned in the RpeKey element of the Expense Report Full Details v1.1 function, and as part of the Report-Entry-Details-Url value returned by this function. |
Request Headers
- Authorization header with OAuth token for valid Concur user. The OAuth Consumer must have one of the following roles to post entries for reports that they do not own: Web Services Admin for Professional, or Can Administer for Standard.
Payload
This request should contain a ReportEntries parent element with an Expense parent element for each included entry. The Expense element contains the following child elements:
| Element | Required (must contain value)? | Description |
|---|---|---|
| CrnCode | Y | The 3-letter ISO 4217 currency code for the expense transaction amount. Example: USD. |
| ExpKey | Y | The expense type key for the expense. Required for new or updated entries. Expense Type Keys are returned in the ExpKey element by the Get Expense Group Configuration function. The expense type key cannot be modified when updating expense entries. |
| Description | Depends on configuration | The description for the expense, also known as business purpose. This information is returned in the BusinessPurpose element by the Get Report Details function. Refer to the Processes > Post Expense Report Data section of Expense Report for the steps necessary to gather required field information. |
| TransactionDate | Y, for new entries | The date the expense was incurred. Format: YYYY-MM-DD |
| TransactionAmount | Y | The total amount of the expense in the original currency, with up to three decimal places. Example: 123.654 |
| LocationID | Depends on configuration | The Location code. May be required, if the City field is required. Use the Get Location function to retreive the valid values for this field. Refer to the Processes > Post Expense Report Data section of Expense Report for the steps necessary to gather required field information. |
| OrgUnit1 through OrgUnit6 | Depends on configuration | The Expense Entry Form org unit fields. May be required depending on configuration. Refer to the Processes > Post Expense Report Data section of Expense Report for the steps necessary to gather required field information. |
| Custom1 through Custom40 | Depends on configuration | The Expense Entry Form custom fields. May be required depending on configuration. Refer to the Processes > Post Expense Report Data section of Expense Report for the steps necessary to gather required field information. NOTE: If any of the custom fields are configured to contain list values, please refer to the Posting Custom List Items page for information on how to correctly submit list item values. |
| ExchangeRate | N | The exchange rate between the transaction and posted amounts. This element is typically not provided. If this element is empty for transactions in a currency different than the user's reimbursement currency, Expense will use the company's configured exchange rates to determine the posted amount for the transaction. If the system is not able to determine the exchange rate, the request will return an HTTP 500 error. |
| Comment | Depends on configuration | The expense entry comment. Max length: 2000. Refer to the Processes > Post Expense Report Data section of Expense Report for the steps necessary to gather required field information. |
| VendorDescription | N, but recommended for sandbox | This element contains the descriptive text for the vendor for the entry. This field is not required to successfully post an entry, however the field is a required field for expense entries in the developer sandbox. If this field is not provided for the sandbox, you will see an exception in the user interface stating that a required field is missing. |
| IsPersonal | N | Whether the expense entry is a personal expense. Personal expenses are not reimbursed in Concur Expense. Format: Y/N |
| PaymentTypeID | N | The unique identifier for the payment type for the expense entry. Use the PaymentTypeID value from the Get Expense Group Configuration endpoint. If you do not provide this value, the payment type defaults to Cash. The supported Payment Type Codes are: Cash and Company Paid. The Pending Card Transaction system payment type is also supported, if the client has configured their company to use it. |
NOTES
- The minimum fields required for new expense entries are: CrnCode, ExpKey, TransactionDate, and TransactionAmount. The required fields that depend on configuration will not prevent an expense entry from being saved. If you create an entry with only the minimum fields, any additional configured required fields will cause the expense entry to have an exception in the user interface. The user will have to fill in the required fields before he/she can save any updates to the entry.
- The update request must include the ExpKey and TransactionAmount fields. All other fields only need to be included if they were updated.
- Update requests cannot change the ExpKey for an existing entry.
XML Example Request
POST https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nxxKgLlnROz$sQ6SKJFjLNs4OWBErcJ8yX/entry/ HTTP/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
<ReportEntries xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03">
<Expense>
<CrnCode>USD</CrnCode>
<ExpKey>BUSPR</ExpKey>
<Description>Business Promotions</Description>
<TransactionDate>2011-01-12</TransactionDate>
<TransactionAmount>29.23</TransactionAmount>
<Comment>Brochure sample</Comment>
<VendorDescription>Kinkos</VendorDescription>
<IsPersonal>N</IsPersonal>
</Expense>
<Expense>
<CrnCode>USD</CrnCode>
<ExpKey>BRKFT</ExpKey>
<Description>Description</Description>
<TransactionDate>2011-01-12</TransactionDate>
<TransactionAmount>15.54</TransactionAmount>
<Comment>Breakfast meeting</Comment>
<VendorDescription>Starbucks</VendorDescription>
<IsPersonal>N</IsPersonal>
</Expense>
</ReportEntries>
Response
Supported Content Types
application/xml
Payload
This request will return a ReportEntryStatusList parent element with the ReportEntryStatus child element for each posted entry. The ReportEntryStatus element will contain the following child elements:
| Element | Description |
|---|---|
| Index | The entry's sequence in the request. |
| Status | The status of the request. |
| Message | When the status is FAILED, the details of the failure appear in this element. |
| Report-Entry-Details-Url | The URI to get the expense entry details. |
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
<ReportEntryStatusList xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ReportEntryStatus>
<Index>1</Index>
<Status>SUCCESS</Status>
<Report-Entry-Details-Url>https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nxxKgLlnROz$sQ6SKJFjLNs4OWBErcJ8yX/entry/nE0avYnILN9mHdTErNSd2pH45udFoNQ$po</Report-Entry-Details-Url>
</ReportEntryStatus>
<ReportEntryStatus>
<Index>2</Index>
<Status>SUCCESS</Status>
<Report-Entry-Details-Url>https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nxxKgLlnROz$sQ6SKJFjLNs4OWBErcJ8yX/entry/awEDvYnILN9g$s6lCFX0jFBWmHAiTYYf9C</Report-Entry-Details-Url>
</ReportEntryStatus>
</ReportEntryStatusList>
Expense Entry Attendee v2
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
NOTE: Find the newer version 3.0 here.
The Expense Entry Attendees manages the relationship between the attendees and the expense report and entry, for the specified expense entry. This resource does not include the full attendee information, which can be accessed using the Get Attendees function.
URI
https://www.concursolutions.com/api/expense/expensereport/v2.0/report/{reportID}/entry/{entryID}/attendees
PUT Expense Entry Attendees
This allows the developer to specify which existing attendees are associated to the specified entry. It also gives the developer the option to provide the values for the Entry-Attendee association. The list of attendees in the request will replace any existing associated attendees, so the developer must include all attendees in the request. This function cannot be used to create new attendees.
Request
Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
{_reportId_} |
Required | The unique identifier for the expense report. This value is returned in the ReportID element by the Get Report Details function. |
{_entryId_}/attendees |
Required | The unique identifier for the expense entry and the Attendees keyword. This value is returned in the ReportEntryID element by the Get Report Details function. |
Headers
- Authorization - Authorization header with OAuth token for valid Concur user. The OAuth user must have one of the following roles in Expense:
- Expense User: This role allows the user to modify their own reports.
- Web Services Administrator (Professional/Premium): This role allows the user to modify reports for all users.
- Can Administer (Standard/Sandbox): This role allows the user to modify reports for all users.
- Content-Type
application/xmlapplication/json
Payload
XML: The request will contain an EntryAttendees parent element with an Attendee child element for each attendee associated to the entry.
JSON: The request string will contain an object for each attendee associated to the entry.
The request must include all attendees associated to the entry. To detach a previously attached attendee, use a Put request excluding the attendee. The function always associates only the attendees specified in the Put. To not modify the element or name/value pair value, provide a nill (XML) or null (JSON) value, or use the same value as you received in the Get Expense Entry Attendees response.
Attendee elements
The Attendee element (XML) or attendee object (JSON) must contain all of the following elements(XML) or name/value pairs(JSON):
| Element Name | Data Type | Description |
|---|---|---|
| Amount | decimal | The portion of the Entry Transaction Amount assigned to this attendee. |
| AssociatedAttendeeCount | int | The count of attendees associated to this attendee. A count greater than 1 means there are unnamed attendees associated with this attendee. |
| AttendeeID | string | The unique identifier for the attendee. |
| EntryAttendeeCustom1 | string | The value for Entry-Attendee custom fields 1-5. Varies based on configuration. |
| EntryAttendeeCustom2 | string | The value for Entry-Attendee custom fields 1-5. Varies based on configuration. |
| EntryAttendeeCustom3 | string | The value for Entry-Attendee custom fields 1-5. Varies based on configuration. |
| EntryAttendeeCustom4 | string | The value for Entry-Attendee custom fields 1-5. Varies based on configuration. |
| EntryAttendeeCustom5 | string | The value for Entry-Attendee custom fields 1-5. Varies based on configuration. |
Response
Headers
- Content-Type
application/xmlapplication/json
Examples
XML example request
PUT https://www.concursolutions.com/api/expense/expensereport/v2.0/report/9d8ea1kole$sis293mn38dh/entry/8sle90wikl3h$halwnk$lakdjw83/attendees HTTP/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
<EntryAttendees xmlns="http://www.concursolutions.com/api/expense/expensereport/2012/07" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Attendee>
<Amount>2422.00000000</Amount>
<AssociatedAttendeeCount>1</AssociatedAttendeeCount>
<AttendeeID>nFaAj0ncBso0sBd8ejqrxLHz1FfmhJ69b</AttendeeID>
<EntryAttendeeCustom1>fg6rt</EntryAttendeeCustom1>
<EntryAttendeeCustom2>9808</EntryAttendeeCustom2>
<EntryAttendeeCustom3>64564drd</EntryAttendeeCustom3>
<EntryAttendeeCustom4>352dsxcvs</EntryAttendeeCustom4>
<EntryAttendeeCustom5 i:nil="true"/>
</Attendee>
</EntryAttendees>
JSON example request
PUT https://www.concursolutions.com/api/expense/expensereport/v2.0/report/9d8ea1kole$sis293mn38dh/entry/8sle90wikl3h$halwnk$lakdjw83/attendees HTTP/1.1
Authorization: OAuth {access token}
Content-Type: application/json
[
{
"AttendeeID": "nFaAj0ncBs$puDs5XxZfOc6L5go8EJIueY",
"Amount": "807.33000000",
"AttendeeCount" :"0",
"Custom1": "dfg",
"Custom2": "7686",
"Custom3": "89080990-90-5464",
"Custom4": "56sdsd sf",
"Custom5": null
},
{
"AttendeeID": "nFaAj0ncBso0sBd8ejqrxLHz1FfmhJ69b",
"Amount": "707.33000000",
"AttendeeCount" :"0",
"Custom1": "fg6rt",
"Custom2": "9808",
"Custom3": "64564drd",
"Custom4": "352dsxcvs",
"Custom5": null
}
]
Example response
200 OK
GET Expense Entry Attendees
Retrieves the expense entry attendees for the specified expense entry. This function requires the v2.0 expense entry attendee resource.
Request
Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
{_reportId_} |
Required | The unique identifier for the expense report. This value is returned in the ReportID element by the Get Report Details function. |
{_entryId_}/attendees |
Required | The unique identifier for the expense entry and the Attendees keyword. This value is returned in the ReportEntryID element by the Get Report Details function. |
Headers
- Authorization header - Authorization header with OAuth token for valid Concur user. Required.
- Content-Type
application/xmlapplication/json
Response
Headers
- Content-Type
application/xmlapplication/json
Payload
This request will return an Attendees parent element with an Attendee child element for each attendee. The Attendee element will have the following child elements.
| Element Name | Data Type | Description |
|---|---|---|
| Amount | decimal | The portion of the Entry Transaction Amount assigned to this attendee. |
| AssociatedAttendeeCount | int | The count of attendees associated to this attendee. A count greater than 1 means there are unnamed attendees associated with this attendee. |
| AttendeeID | string | The unique identifier for the attendee. |
| EntryAttendeeCustom1 | string | The value for Entry-Attendee custom fields 1-5. Varies based on configuration. |
| EntryAttendeeCustom2 | string | The value for Entry-Attendee custom fields 1-5. Varies based on configuration. |
| EntryAttendeeCustom3 | string | The value for Entry-Attendee custom fields 1-5. Varies based on configuration. |
| EntryAttendeeCustom4 | string | The value for Entry-Attendee custom fields 1-5. Varies based on configuration. |
| EntryAttendeeCustom5 | string | The value for Entry-Attendee custom fields 1-5. Varies based on configuration. |
Examples
XML example request
GET https://www.concursolutions.com/api/expense/expensereport/v2.0/report/nxxKgLlnROz3zHJBCRksaas23dsfs/entry/n7We3qWw99u1KoWTMaLhSC$pXBYzQ1UDhn/attendees HTTP/1.1
Authorization: OAuth {access token}
JSON example request
GET https://www.concursolutions.com/api/expense/expensereport/v2.0/report/nxxKgLlnROz3zHJBCRksaas23dsfs/entry/n7We3qWw99u1KoWTMaLhSC$pXBYzQ1UDhn/Attendees HTTP/1.1
Authorization: OAuth {access token}
XML example response
HTTP/1.1 200 OK
Content-Type: application/xml
<EntryAttendees xmlns="http://www.concursolutions.com/api/expense/expensereport/2012/07" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Attendee>
<Amount>2422.00000000</Amount>
<AssociatedAttendeeCount>1</AssociatedAttendeeCount>
<AttendeeID>nFaAj0ncBso0sBd8ejqrxLHz1FfmhJ69b</AttendeeID>
<EntryAttendeeCustom1>Medical</EntryAttendeeCustom1>
<EntryAttendeeCustom2>North America</EntryAttendeeCustom2>
<EntryAttendeeCustom3>Canada</EntryAttendeeCustom3>
<EntryAttendeeCustom4>Vancouver</EntryAttendeeCustom4>
<EntryAttendeeCustom5 i:nil="true"/>
</Attendee>
</EntryAttendees>
JSON example response
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"AttendeeID": "nFaAj0ncBs$puDs5XxZfOc6L5go8EJIueY",
"Amount": "807.33000000",
"AttendeeCount": "0",
"Custom1": "Medical",
"Custom2": "North America",
"Custom3": "Canada",
"Custom4": "Vancouver",
"Custom5": null
},
{
"AttendeeID": "nFaAj0ncBso0sBd8ejqrxLHz1FfmhJ69b",
"Amount": "707.33000000",
"AttendeeCount": "0",
"Custom1": "Medical",
"Custom2": "North America",
"Custom3": "Canada",
"Custom4": "Vancouver",
"Custom5": null
}
]
Expense Group Configurations v1.1
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
The Expense Group Configuration contains the list of Expense Polices, Expense Types and Payment Types for the Expense Group the user specified in the OAuth access token is assigned to.
Resource URI
https://www.concursolutions.com/api/expense/expensereport/v1.1/ExpenseGroupConfiguration/
Get an expense group configuration
Retrieves the list of Expense Polices, Expense Types and Payment Types for the Expense Group the user specified in the OAuth access token is assigned to. Each Expense Policy contains a list of valid Expense Types. The Payment Types are associated with the user's Expense Group and apply to all the returned policies. Only the payment types that are valid for the Post Expense Entry endpoint are returned.
NOTE: The Concur Expense product is highly configurable, and each client may have a unique set of payment types. If a payment type is not included in the response, it is not available for use with this client.
Request
Parameters
None
Headers
- Authorization - Authorization header with OAuth token for valid Concur user.
- Accept - application/xml
Response
Payload
This request will return an ExpenseGroupConfiguration parent element. The ExpenseGroupConfiguration has a PaymentTypes child element and a PolicyAndExpenseTypesList child element.
The PaymentTypes child element has a PaymentType child element for each configured payment type. The PolicyAndExpenseTypesList child element has a PolicyandExpenseTypes child element for each policy configured for this expense group.
PaymentType elements
| Element | Description |
|---|---|
| PaymentTypeID | The encrypted key for the payment type. This is the unique identifier for the payment type. |
| PaymentTypeName | The name of the payment type. |
PolicyandExpenseTypes elements
| Element | Description |
|---|---|
| PolicyKey | The ID value of the policy. |
| PolicyName | The name of the policy. |
| ExpenseTypes | The parent element for the list of expense types in the policy. It contains an ExpenseType child element for each expense type in the policy. |
ExpenseType elements
| Element | Description |
|---|---|
| ExpKey | The expense type key. |
| ExpName | The label of the expense type. |
| ParentExpKey | The code of the expense type's parent. |
| ParentExpName | The label of the expense type's parent. |
| SpendCategory | The spend category assigned to the expense type for reporting purposes. |
Examples
XML example request
GET https://www.concursolutions.com/api/expense/expensereport/v1.1/ExpenseGroupConfiguration/ HTTP/1.1
Authorization: OAuth {access token}
XML example of successful response
HTTP/1.1 200 OK
Content-Type: application/xml
<ExpenseGroupConfiguration xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<PaymentTypes>
<PaymentType>
<PaymentTypeID>nr74tQrD8PorkF6yvS0Sm8ZeSGsw</PaymentTypeID>
<PaymentTypeName>Cash</PaymentTypeName>
</PaymentType>
<PaymentType>
<PaymentTypeID>nr7AuTtrvkXwLOzEejFruFO$sN7eo</PaymentTypeID>
<PaymentTypeName>Company Paid</PaymentTypeName>
</PaymentType>
</PaymentTypes>
<PolicyAndExpenseTypesList>
<PolicyAndExpenseTypes>
<PolicyKey>ndrF8hjzl9FhH1Lvs0EuK1gi7LISbetxc</PolicyKey>
<PolicyName>CA Expense Policy</PolicyName>
<ExpenseTypes>
<ExpenseType>
<ExpKey>BUSPR</ExpKey>
<ExpName>Promotional Items</ExpName>
<ParentExpKey>PROMO</ParentExpKey>
<ParentExpName>Business Promotions</ParentExpName>
</ExpenseType>
<ExpenseType>
<ExpKey>TRDSH</ExpKey>
<ExpName>Trade Shows</ExpName>
<ParentExpKey>PROMO</ParentExpKey>
<ParentExpName>Business Promotions</ParentExpName>
</ExpenseType>
<ExpenseType>
<ExpKey>LOCPH</ExpKey>
<ExpName>Local Phone</ExpName>
<ParentExpKey>COMMU</ParentExpKey>
<ParentExpName>Communications</ParentExpName>
</ExpenseType>
</ExpenseTypes>
</PolicyAndExpenseTypes>
</PolicyAndExpenseTypesList>
</ExpenseGroupConfiguration>
Expense Report Header v1.1
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
NOTE: Find the newer version 3.0 here.
The expense report header contains classification information for the expense report, and serves as the container for the expense entries.
Resource URI
https://www.concursolutions.com/api/expense/expensereport/v1.1/report/
Post an expense report header
Posts the expense report header information for a new or existing report for the user specified in the OAuth access token. If the OAuth consumer has the necessary roles, they can update reports that belong to other users. Use this function to create a report, then use the Post Expense Entry function to send expense line items.
NOTES:
- Posting expense report information is a multi-stage process.
- Reports with the following statuses can't be modified:
- Processing Payment
- Paid
- Payment Confirmed
Request
Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
{_reportId_} |
Optional | The unique identifier for the report. Only used when updating an existing report. |
Example:
https://www.concursolutions.com/api/expense/expensereport/v1.1/report/{reportId}
URI Source: The reportId value is returned by the Get List of Reports and Get Report Details functions, and as part of the Report-Details-Url element returned by this function.
Headers
- Authorization - Authorization header with OAuth token for valid Concur user. Required.
- Content-Type - application/xml
The Concur user must have one of the following roles in Expense:
- Expense User: This role allows the user to create and modify their own reports.
- Web Services Administrator (Professional/Premium): This role allows the user to modify reports for all users.
- Can Administer (Standard): This role allows the user to modify reports for all users.
Payload
This request should contain a Report parent element with the following child elements.
| Element | Required (must contain value)? | Description |
|---|---|---|
| Name | Y | The expense report name. |
| Purpose | Depends on configuration | The business purpose of the report. Maximum length: 500. |
| Comment | Depends on configuration | The report header comment. Maximum length: 500. |
| OrgUnit1 through OrgUnit6 | Depends on configuration | The custom Organization Unit fields. May be required depending on configuration. Refer to the Processes > Post Expense Report Data section of Expense Report for the steps necessary to gather required field information. |
| Custom1 through Custom20 | Depends on configuration | The custom fields on the Expense Report Header form. May be required depending on configuration. Refer to the Processes > Post Expense Report Data section of Expense Report for the steps necessary to gather required field information. NOTE: If any of the custom fields are configured to contain list values, refer to the Posting Custom List Items page for information on how to correctly submit list item values. |
| UserDefinedDate | Depends on configuration | The date the user selected for the report. Format: YYYY-MM-DD hh:mm:ss.0 |
Response
Headers
- Content-Type - application/xml
Payload
The response will include a ReportDetails parent element. This element will contain a ReportStatus child element. The ReportStatus element will contain the following child elements.
| Element | Description |
|---|---|
| Status | The status of the request. |
| Report-Details-Url | The URI to use when posting report details to this report. |
Examples
XML example of new report request
POST https://www.concursolutions.com/api/expense/expensereport/v1.1/report HTTP/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
<Report xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03">
<Name>January Expenses</Name>
<Purpose>All expenses for January</Purpose>
<Comment>Includes Client Meetings.</Comment>
<OrgUnit1>US</OrgUnit1>
<OrgUnit2>NW</OrgUnit2>
<OrgUnit3>Redmond</OrgUnit3>
<Custom1>Client</Custom1>
<Custom2>Local</Custom2>
<UserDefinedDate>2011-03-26 15:15:07.0</UserDefinedDate>
</Report>
XML example of successful response
HTTP/1.1 200 OK
Content-Type: application/xml
<ReportDetails>
<ReportStatus xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Status>SUCCESS</Status>
<Report-Details-Url>https://www.concursolutions.com/api/expense/expensereport/v1.1/report/nxxKgLlnRODp$sie8Hq1UviOJ2AbpS7dCP</Report-Details-Url>
</ReportStatus>
</ReportDetails>
Post Report Header Batch Request
Posts a batch of expense report headers. The expense report header contains classification information for the expense report. Use this endpoint to create a batch of reports, then use the Post Expense Entry function to send expense line items. All batch operations allow up to 1000 headers per batch. If a batch request with over 1000 headers is sent, only the first 1000 headers in the batch will be processed.
NOTE: Posting expense report information is a multi-stage process. Refer to the Processes section of the Expense Report Web Service page for the steps required to post new expense reports and entries.
Request
Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
batch |
required | The batch keyword. |
Example:
https://www.concursolutions.com/api/expense/expensereport/v1.1/report/batch
Headers
- Authorization
- Content-Type - application/xml
The Concur user must have one of the following roles in Expense:
- Expense User: This role allows the user to create and modify their own reports.
- Web Services Administrator (Professional/Premium): This role allows the user to create and modify reports for all users.
- Can Administer (Standard): This role allows the user to create and modify reports for all users.
Payload
This request should contain a batch parent element with a Report parent element for each included report. The Report element contains the following child elements.
Report elements
| Element | Required (must contain value)? | Description |
|---|---|---|
| Index | Y | The header's location in the batch. Should start at 1 and increment sequentially. This value is used to identify the record if there is an error. |
| LoginId | Y | The report owner's Concur login ID. |
| Name | Y | The expense report name. |
| Purpose | Depends on configuration | The business purpose of the report. Maximum length: 500. |
| Comment | Depends on configuration | The report header comment. Maximum length: 500. |
| OrgUnit1 through OrgUnit6 | Depends on configuration | The custom Organization Unit fields. May be required depending on configuration. Refer to the Processes > Post Expense Report Data section of Expense Report for the steps necessary to gather required field information. |
| Custom1 through Custom20 | Depends on configuration | The custom fields on the Expense Report Header form. May be required depending on configuration. Refer to the Processes > Post Expense Report Data section of Expense Report for the steps necessary to gather required field information. NOTE: If any of the custom fields are configured to contain list values, please refer to the Posting Custom List Items page for information on how to correctly submit list item values. |
| UserDefinedDate | Depends on configuration | The date the user selected for the report. Format: YYYY-MM-DD hh:mm:ss.0 |
Response
Headers
- Content-Type - application/xml
Payload
This request will return a report-batch-result parent element with the following child elements.
| Element | Description |
|---|---|
| records-succeeded | The number of records processed that were successfully added. |
| records-failed | The number of records processed that were not successfully added. |
| errors | This will contain an error parent element for each record failure. For details about the error child elements, see the error child elements table below. |
| ReportDetails | This parent element will contain a ReportStatus child element for all report headers that did not cause an error. For details about the ReportStatus child elements, see the ReportStatus child elements table below. |
error elements
| Element | Description |
|---|---|
| Index | The header's location in the batch |
| LoginID | The user's Concur login ID. |
| message | The error message. |
ReportStatus elements
| Element | Description |
|---|---|
| Status | The status of the request. |
| Report-Details-Url | The URI to use when posting report details to this report. |
Examples
XML example request
POST https://www.concursolutions.com/api/expense/expensereport/v1.1/report/batch HTTP/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
<batch xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03">
<Report>
<Index>1</Index>
<LoginId>cmiller@example.com</LoginId>
<Name>January Expenses</Name>
<Purpose>All expenses for January</Purpose>
<Comment>Includes Client Meetings.</Comment>
<OrgUnit1>US</OrgUnit1>
<OrgUnit2>NW</OrgUnit2>
<OrgUnit3>Redmond</OrgUnit3>
<Custom1>Client</Custom1>
<Custom2>Local</Custom2>
<UserDefinedDate>2011-01-26 12:15:00.0</UserDefinedDate>
</Report>
<Report>
<Index>2</Index>
<LoginId>tbrown@example.com</LoginId>
<Name>Trip to New York </Name>
<Purpose>New York Sales Meeting </Purpose>
<Comment></Comment>
<OrgUnit1>US</OrgUnit1>
<OrgUnit2></OrgUnit2>
<OrgUnit3>Tucson</OrgUnit3>
<Custom1>Client</Custom1>
<Custom2>Remote</Custom2>
<UserDefinedDate>2011-02-04 15:25:07.0</UserDefinedDate>
</Report>
</batch>
XML example response with success and failure
HTTP/1.1 200 OK
Content-Type: application/xml
<report-batch-result xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<records-succeeded>1</records-succeeded>
<records-failed>1</records-failed>
<errors>
<error>
<Index>2</Index>
<LoginID>tbrown@example.com</LoginID>
<message>Invalid Value for:OrgUnit2</message>
</error>
</errors>
<ReportDetails>
<ReportStatus >
<Index>1</Index>
<Status>SUCCESS</Status>
<Report-Details-Url>https://www.concursolutions.com/api/expense/expensereport/v1.1/nxxKgLlnRODp$sie8Hq1UviOJ2AbpS7dCP</Report-Details-Url>
</ReportStatus>
</ReportDetails>
</report-batch-result>
Expense Reports List v1.1
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
Get list of expense reports
Retrieves a list of reports. This endpoint can be used to view reports for one user, or to view recent reports for the entire company. If you get reports for one user, you can view reports owned by the user specified in the OAuth access token. If you choose to get all the reports for the company, you must use the LastModified date query string to view reports for a 24 hour period. You can provide an optional View to target search results. If no view or date string is provided, the web service will return all Recent reports for the specified user. If the LastModified query string is provided, the results do not filter based on the specified user. This endpoint can support frequent requests, where the developer tracks the previous date/time that the endpoint was called, and uses that as the date/time for the next request.
Request
URI
GET https://www.concursolutions.com/api/expense/expensereport/v1.1/ReportsList/{_View_}
Parameters
This URI can be appended with the following optional report View values:
| Value | Description |
|---|---|
RECENT |
Returns all reports that have been modified in the last 31 days for the specified user. |
ACTIVE |
Returns all unsubmitted and unpaid (payment status is not Paid) reports for the specified user. |
UNSUBMITTED |
Returns all unsubmitted reports for the specified user. |
PENDING |
Returns all pending reports for the specified user. |
APPROVED |
Returns all approved reports for the specified user. |
PROCESSED |
Returns all processed reports for the specified user. |
PAID |
Returns all paid reports for the specified user. |
PAYMENTCONFIRMED |
Returns all paid reports for the specified user. |
FORTHISMONTH |
Returns all reports with a create date in this month by the specified user. |
FORLASTMONTH |
Returns all reports with a create date in the previous month by the specified user. |
FORTHISQUARTER |
Returns all reports with a create date in this calendar quarter by the specified user. |
FORLASTQUARTER |
Returns all reports with a create date in the previous calendar quarter by the specified user. |
FORTHISYEAR |
Returns all reports with a create date in this year by the specified user. |
FORLASTYEAR |
Returns all reports with a create date in in the past year by the specified user. |
TOAPPROVE |
Returns all reports pending approval from the specified user. |
APPROVEDTHISMONTH |
Returns all reports approved or pending approval from the specified user in the current month. |
APPROVEDLASTMONTH |
Returns all reports approved by the specified user in the current month. |
APPROVEDTHISQUARTER |
Returns all reports approved or pending approval from the specified user in the current calendar quarter. |
APPROVEDLASTQUARTER |
Returns all reports approved by the specified user in the previous calendar quarter. |
APPROVEDTHISYEAR |
Returns all reports approved or pending approval from the specified user in the current calendar year. |
APPROVEDLASTYEAR |
Returns all reports approved by the specified user in the previous calendar year. |
This request can include an optional query string specifying the last modified date (in Coordinated Universal Time, aka UTC) of the reports. This query string will return the reports modified within 24 hours after the supplied date. You can provide the time in UTC, and the query will return the reports with a last modified date that is greater (up to 24 hours after the time) or equal to the supplied time. The provided date/time can be any time between now and the first date of expense report creation in the database. The format is either the date or the date and time combined:
/api/expense/expensereport/v1.1/reportslist/UNSUBMITTED/LastModified?date=2011-07-06T12:23:00
or
/api/expense/expensereport/v1.1/reportslist/UNSUBMITTED/LastModified?date=2011-07-06
The LastModified query string is supported only with the following statuses: ALL, ACTIVE, UNSUBMITTED, APPROVED, PENDING, PROCESSED, PAID, PAYMENTCONFIRMED, RECENT, TOAPPROVE
NOTES:
- The LastModified query string returns reports for all users, ignoring the user account specified in the OAuth access token.
- The ApprovalURL element does not appear when using the LastModified query.
Headers
- Content-Type - application/xml
Response
Headers
- Content-Type - application/xml
Payload
This request will return a ReportsList parent element with an xmlns version attribute and a ReportSummary child element for each report. The ReportSummary elements will have the following child elements:
| Value | Description |
|---|---|
ApprovalURL |
The URL the user can use to log in to Concur to approve the report. This element appears when requesting the TOAPPROVE status, and does not appear when using the DateModified query. This URL works only when the company does not use Concur SSO with the Enforce option. |
ReportName |
The name of the report. |
ReportId |
The unique identifier for the report, which appears in the Concur Expense UI. |
ReportTotal |
The total amount of the report. |
ReportCurrency |
The 3-letter ISO 4217 currency code for the expense report currency. |
ReportDate |
The create date of the report. |
LastComment |
The text of the most recent comment on the report. |
Report-Details-Url |
The URL to access the report summary details. |
Report-Full-Details-Url |
The URL to access the full report details. |
ExpenseUserXUserID |
The User ID of the user this report belongs to. |
ApproverXUserID |
The User ID of the user's expense approver. |
EmployeeName |
The name of the expense report owner. Format: Firstname Lastname |
Notes:
The ApprovalURL provides a link to Expense that can be used with SSO in most circumstances. The link can be put into a browser window, then the approver is automatically logged into Expense and the expense report opens if:
- The company uses a Concur-supported SSO platform (and does not use the Enforce option) and...
- The approver is currently on the company network or is using VPN
Otherwise, when the approver clicks the link, the Expense login page appears. The approver logs in and follows the normal steps for approving reports.
Report Full Details v1.1
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
Retrieves the full set of information for the report. Includes the Report Header, Entry, Attendee, Itemization and Allocation details.
Get expense report full details
Request
URI
This URI is returned in the Report-Full-Details-Url element by the Expense Reports List v1.1 endpoint. The report key is the encrypted database key for the report.
GET https://www.concursolutions.com/api/expense/expensereport/v1.1/reportfulldetails/_{reportKey}_
Headers
- Content-Type - application/xml
Response
Headers
- Content-Type - application/xml
Payload
This request will return a <ReportDetails> parent element with an xmlns version attribute and the following child elements:
| Element | Description |
|---|---|
X-UserID |
The user ID of the report owner. |
ReportId |
The unique identifier for the report, which appears in the Concur Expense UI. |
ReportName |
The name of the report. |
Purpose |
The information from the Business Purpose field. |
CrnCode |
The 3-letter ISO 4217 currency code for the expense report currency. The expense report currency is defined as the report creator's default reimbursement currency. |
ApsKey |
The approval status code for the report. |
ReportDate |
The date from the report header. Format: YYYY-MM-DDThh:mm:ss |
CreationDate |
The date the report was created. Format: YYYY-MM-DDThh:mm:ss |
ReceiptImageUrl |
The URL to access the image associated with the report. This URL is only valid for 30 minutes after the web service call. |
HasException |
Whether the report has exceptions. Format: Y/N |
EverSentBack |
Whether the report has ever been sent back to the employee. Format: Y/N |
EmployeeName |
The name of the employee who created the report. |
ApvStatusName |
The approval status name for the report. |
PayKey |
The unique identifier for the payment status of the report. |
PayStatusName |
The payment status of the report. |
PaidDate |
The date the report was extracted for payment. This element has an attribute named i:nil. If the value for this element is null, the i:nil attribute will be set to true. Format: YYYY-MM-DDThh:mm:ss |
SubmitDate |
The date the report was submitted. |
EntryCount |
The number of expense entries in the report. This count includes itemized entries. |
LedgerName |
The name of the expense report ledger. |
OrgUnit1 through OrgUnit6 |
The details from the Org Unit custom fields. These may not have data, depending on configuration. |
Custom1 through Custom20 |
The details from the Custom fields. These may not have data, depending on configuration. If the custom field is a list field, the data will be returned as: (list item short code) list item name. List Field Example: |
PolKey |
The unique identifier of the policy that applies to this report. |
RptKey |
The encrypted database key for the report, which is used as the unique identifier in other web service requests. |
ReportTotal |
The total amount of the report. |
PersonalExpenses |
The total amount of expenses marked as personal. |
AmountDueEmployee |
The total amount due to the employee for the report. |
AmountDueCompanyCard |
The total amount due to the company card for the report. |
TotalClaimedAmount |
The total amount of all non-personal expenses in the report. |
TotalApprovedAmount |
The total amount of approved expenses in the report. |
WorkflowActionURL |
The URL to post a workflow action to the report using the Post Report Workflow Action endpoint. |
Entries |
This parent element has a Count attribute indicating the number of entries (not including itemization entries) that are included in the report. It has an ExpenseEntry child element for each entry. Refer to the Expense Entry Child Elements table for more information. |
Expense Entry Child Elements
| Element | Description |
|---|---|
ReceiptRequired |
Whether the original receipt is required for the entry. |
ImageRequired |
Whether a receipt image is required for the entry. |
EreceiptId |
The ID for the attached e-receipt, if available. |
Custom1 through Custom40 |
The details from the Custom fields. These may not have data, depending on configuration. If the custom field is a list field, the data will be returned as: (list item short code) list item name. List Field Example: |
RpeKey |
The ID of the report entry. |
RptKey |
The encrypted database key of the report. |
ExpKey |
The expense type key for the expense entry. Expense Type Keys are returned in the ExpKey element by the Expense Group Configuration endpoint. |
FormKey |
The key for the expense entry form. |
ReceiptImageId |
The unique identifier for the image associated with the entry. |
ExpName |
The expense type name. |
SpendCategory |
The spend category specified for this expense type. Varies by client, used in reporting. |
BusinessPurpose |
The text from the Business Purpose field of the entry. |
HasVat |
Whether the entry contains VAT data. |
ExchangeRate |
The exchange rate that applies to the entry. |
TransactionAmount |
The amount of the expense entry in the original transaction currency. |
PostedAmount |
The amount of the expense entry in the user's reimbursement currency. The user's reimbursement currency is returned in the <CrnCode element for the report. |
ApprovedAmount |
The approved amount of the expense entry in the user's reimbursement currency. The user's reimbursement currency is returned in the <CrnCode element for the report. |
TransactionCurrencyName |
The name of the transaction currency. |
VendorDescription |
The vendor name of the expense entry, which can be entered manually by the user or imported from the card transaction Merchant Name field. |
LocationName |
The location for the expense entry, usually the city name. |
LocationSubdivision |
The location's State, Province, or Country Subdivision. |
LocationCountry |
The location's Country. |
OrgUnit1 through OrgUnit6 |
The details from the Org Unit custom fields. These may not have data, depending on configuration. |
HasComments |
Whether the expense entry has comments. |
CommentCount |
The number of comments associated with the expense entry. |
PaymentTypeKey |
The key for the payment type. |
IsItemized |
Whether the expense entry is itemized. |
HasExceptions |
Whether the expense entry has exceptions. |
IsPersonal |
Whether the expense entry is marked as personal. |
HasAttendees |
Whether the expense entry has attendees. |
HasAllocation |
Defines the amount of allocations for the expense. Possible values are: P, for partial allocation, F, for full allocation, or N, for no allocation. |
IsCreditCardCharge |
Whether the expense came from a credit card feed. |
AttendeeCount |
The number of attendees associated with the expense entry. |
IsPersonalCardCharge |
Whether the expense came from a personal card feed. |
TransactionDate |
The date of the expense entry. |
LastModifiedDate |
The date the expense entry was last changed. |
ItemizationList |
The list of itemizations for the expense entry. This parent element is empty if there are no itemizations. When the report has itemizations, this element contains an ItemizationEntry Details element for each itemization. Refer to the Itemization Entry Details Child Elements table for more information. |
Itemization Entry Details Child Elements
| Element | Description |
|---|---|
Custom1 through Custom40 |
The custom fields associated with the itemization. These may not have data, depending on your configuration. If the custom field is a list field, the data will be returned as: (list item short code) list item name. List Field Example: |
ItemizationKey |
The unique identifier for the itemization. |
ExpenseKey |
The expense type key for the itemization. |
ExpenseName |
The expense type for the itemization. |
BusinessPurpose |
The business purpose field from the report header. |
TransactionAmount |
The amount for the itemization in the expense currency. |
TransactionDate |
The date of the transaction. |
PostedAmount |
The amount for the itemization in the user's reimbursement currency. The user's reimbursement currency is returned in the <CrnCode element for the report. |
ApprovedAmount |
The approved amount of the itemization in the user's reimbursement currency. The user's reimbursement currency is returned in the <CrnCode element for the report. |
HasComments |
Whether the itemization has comments. |
IsPersonal |
Whether the itemization is personal. |
LastModified |
The UTC date when the itemization was last modified. |
AllocationsList |
This parent element contains one Allocations element for each associated allocation. This element will be empty if there are no allocations. The |
Allocations |
This element appears once for each allocation associated with the expense entry if the entry is not itemized. This element will be empty if there are no allocations, or if the ItemizationList element contains the allocation data. This element contains child elements. |
AttendeeDetails |
This parent element appears once for each associated attendee, and contains child elements. |
Allocations List Child Elements
| Element | Description |
|---|---|
Custom1 through Custom20 |
The custom fields associated with the allocation. These may not have data, depending on your configuration. If the custom field is a list field, the data will be returned as: (list item short code) list item name. List Field Example: |
AllocationKey |
The unique alphanumeric identifier for the allocation. |
Percentage |
The percentage of the expense that is included in this allocation. |
AccountCode1 |
The account code for the allocation. |
AccountCode2 |
The second account code for the allocation. This is only populated in rare cases, such as when using travel allowance, where one expense might have an account code for the allowed amount, and a second account code for the overage. |
Allocations Child Elements
| Element | Description |
|---|---|
Custom1 through Custom20 |
The custom fields associated with the allocation. These may not have data, depending on your configuration. If the custom field is a list field, the data will be returned as: (list item short code) list item name. List Field Example: |
AccountCode1 |
The account code for the allocation. |
AccountCode2 |
The second account code for the allocation. This is only populated in rare cases, such as when using travel allowance, where one expense might have an account code for the allowed amount, and a second account code for the overage. |
allocKey |
The unique alphanumeric identifier for the allocation. |
percentage |
The percentage of the expense that is included in this allocation. |
Attendee Details Child Elements
| Element | Description |
|---|---|
Custom1 through Custom20 |
The details from the Custom fields. These may not have data, depending on configuration. If the custom field is a list field, the data will be returned as |
AttendeeType |
The type of attendee. |
FirstName |
The attendee's first name. |
LastName |
The attendee's last name. |
Company |
The attendee's company name. |
ExternalId |
The unique identifier for the attendee, managed outside Concur. |
HasExceptionsPrevYear |
Whether the attendee has exceptions in the previous year, based on yearly total limits for attendees. |
HasExceptionsYtd |
Whether the attendee has exceptions in the current year, based on yearly total limits for attendees. |
IsDeleted |
Whether the attendee is marked as deleted. |
OwnerEmpName |
The name of the employee that owns the attendee record. |
Title |
The attendee's title. |
TotalAmountPrevYear |
The total amount spent on the attendee in the previous calendar year. |
TotalAmountYtd |
The total amount spent on the attendee in the current calendar year. |
VersionNumber |
The attendee's version number. |
AttendeeKey |
Attendee unique identifier within Concur. |
Example
Request
GET http://www.concursolutions.com/api/expense/expensereport/v1.1/reportfulldetails/n6ujbuLd1Arwe45lT7As3ThJYJf2dAsrrEW HTTPS/1.1
Host: www.concursolutions.com
Authentication: OAuth
Response
HTTPS/1.1 200 OK
Content-Type: application/xml
<ReportDetails xmlns:ns="http://www.concursolutions.com/api/expense/expensereport/2011/03" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<X_UserID>cmiller@example.com</X_UserID>
<ReportId>4681D8C33A284E91A46E</ReportId>
<ReportName>Client Meeting </ReportName>
<Purpose>Sales meeting</Purpose>
<CrnCode>USD</CrnCode>
<ApsKey>A_NOTF</ApsKey>
<ReportDate>2011-05-12T00:00:00</ReportDate>
<CreationDate>2011-05-12T14:15:36</CreationDate>
<ReceiptImageUrl>http://www.concursolutions.com/getImage?cid=p0000002tcnl&val=D9EC86BB902B8D48</ReceiptImageUrl>
<HasException>N</HasException>
<EverSentBack>N</EverSentBack>
<EmployeeName>Miller, Chris </EmployeeName>
<ApvStatusName>Not Submitted</ApvStatusName>
<PayKey>P_NOTP</PayKey>
<PayStatusName>Not Paid</PayStatusName>
<PaidDate i:nil="true"/>
<SubmitDate>0001-01-01T00:00:00</SubmitDate>
<EntryCount>2</EntryCount>
<LedgerName>DEFAULT</LedgerName>
<OrgUnit1 />
<OrgUnit2 />
<OrgUnit3 />
<OrgUnit4 />
<OrgUnit5 />
<OrgUnit6 />
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<PolKey>n3VIbuLd1AU4tlT7As3ThJYJf2dADsJ1V</PolKey>
<RptKey>n6ujbuLd1Arwe45lT7As3ThJYJf2dAsrrEW</RptKey>
<ReportTotal>129.00000000</ReportTotal>
<PersonalExpenses>0.00000000</PersonalExpenses>
<AmountDueEmployee>129.00000000</AmountDueEmployee>
<AmountDueCompanyCard>0.00000000</AmountDueCompanyCard>
<TotalClaimedAmount>129.00000000</TotalClaimedAmount>
<TotalApprovedAmount>129.00000000</TotalApprovedAmount>
<WorkflowActionURL>http://www.concursolutions.com/api/expense/expensereport/v1.1/report/Ko9%t8GHpERQVpk$pS2EL6EDHRwi9r$paQS1UqyL6a454QitqQ/WorkFlowAction</WorkflowActionURL>
<Entries Count="2">
<ExpenseEntry>
<ReceiptRequired>N</ReceiptRequired>
<ImageRequired>Y</ImageRequired>
<EreceiptId />
<OrgUnit1 />
<OrgUnit2 />
<OrgUnit3 />
<OrgUnit4 />
<OrgUnit5 />
<OrgUnit6 />
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<Custom21 />
<Custom22 />
<Custom23 />
<Custom24 />
<Custom25 />
<Custom26 />
<Custom27 />
<Custom28 />
<Custom29 />
<Custom30 />
<Custom31 />
<Custom32 />
<Custom33 />
<Custom34 />
<Custom35 />
<Custom36 />
<Custom37 />
<Custom38 />
<Custom39 />
<Custom40 />
<RpeKey>nfUEGTNhWxbXkeT26XlVm9Gdqvbi8hlDa</RpeKey>
<RptKey>nbe1LDA99RdTx0fUEuZiYd5WW8afkjew$p</RptKey>
<X_UserID>cmiller@example.com</X_UserID>
<ExpKey>BUSMEAL</ExpKey>
<FormKey>nnamf5z0cLe4MHs53YwSIjwY0uP8kby5p</FormKey>
<ReceiptImageId />
<ExpName>BUSMEAL</ExpName>
<BusinessPurpose />
<HasVat>N</HasVat>
<ExchangeRate>1.00000000000000</ExchangeRate>
<TransactionAmount>115.00000000</TransactionAmount>
<PostedAmount>115.00000000</PostedAmount>
<ApprovedAmount>115.00000000</ApprovedAmount>
<TransactionCurrencyName>Dollar, United States</TransactionCurrencyName>
<VendorDescription>Mel's Diner </VendorDescription>
<LocationName>Seattle</LocationName>
<LocationSubdivision>WA</LocationSubdivision>
<LocationCountry>US</LocationCountry>
<SpendCategory>Meals and Entertainment</SpendCategory>
<HasComments>N</HasComments>
<CommentCount>0</CommentCount>
<PaymentTypeKey>CASH</PaymentTypeKey>
<IsItemized>Y</IsItemized>
<HasExceptions>N</HasExceptions>
<IsPersonal>N</IsPersonal>
<HasAttendees>Y</HasAttendees>
<HasAllocation>Y</HasAllocation>
<IsCreditCardCharge>N</IsCreditCardCharge>
<AttendeeCount>2</AttendeeCount>
<IsPersonalCardCharge>N</IsPersonalCardCharge>
<TransactionDate>2011-05-19T00:00:00</TransactionDate>
<LastModifiedDate>2011-05-19T14:44:50</LastModifiedDate>
<ItemizationsList>
<ItemizationEntryDetails>
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<Custom21 />
<Custom22 />
<Custom23 />
<Custom24 />
<Custom25 />
<Custom26 />
<Custom27 />
<Custom28 />
<Custom29 />
<Custom30 />
<Custom31 />
<Custom32 />
<Custom33 />
<Custom34 />
<Custom35 />
<Custom36 />
<Custom37 />
<Custom38 />
<Custom39 />
<Custom40 />
<ItemizationKey>nE0avYnILN6vKNUGsh5lCg6vt$sqc9qB$sq</ItemizationKey>
<ExpenseKey>MISCL</ExpenseKey>
<ExpenseName>Miscellaneous</ExpenseName>
<BusinessPurpose>Promo T-shirt</BusinessPurpose>
<TransactionAmount>8.00000000</TransactionAmount>
<TransactionDate>2011-05-19T00:00:00</TransactionDate>
<PostedAmount>8.00000000</PostedAmount>
<ApprovedAmount>8.00000000</ApprovedAmount>
<HasComments>Y</HasComments>
<CommentCount>0</CommentCount>
<IsPersonal>N</IsPersonal>
<LastModified>2011-05-19T14:06:53</LastModified>
<AllocationsList>
<Allocations>
<Custom1>North America</Custom1>
<Custom2>West</Custom2>
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<AllocationKey>ngYn5SB4OUXwHnBjh8$pBIT8oPxe9G$shCi</AllocationKey>
<Percentage>100.00000000%</Percentage>
<AccountCode1>MISC_EXP</AccountCode1>
<AccountCode2 />
</Allocations>
</AllocationsList>
</ItemizationEntryDetails>
<ItemizationEntryDetails>
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<Custom21 />
<Custom22 />
<Custom23 />
<Custom24 />
<Custom25 />
<Custom26 />
<Custom27 />
<Custom28 />
<Custom29 />
<Custom30 />
<Custom31 />
<Custom32 />
<Custom33 />
<Custom34 />
<Custom35 />
<Custom36 />
<Custom37 />
<Custom38 />
<Custom39 />
<Custom40 />
<ItemizationKey>nE0avYnILN6hfJ8LSXF8Qd9WkOkwSp83G</ItemizationKey>
<ExpenseKey>BRKFT</ExpenseKey>
<ExpenseName>Breakfast</ExpenseName>
<BusinessPurpose>Client Meeting</BusinessPurpose>
<TransactionAmount>107.00000000</TransactionAmount>
<TransactionDate>2011-05-19T00:00:00</TransactionDate>
<PostedAmount>107.00000000</PostedAmount>
<ApprovedAmount>107.00000000</ApprovedAmount>
<HasComments>Y</HasComments>
<CommentCount>0</CommentCount>
<IsPersonal>N</IsPersonal>
<LastModified>2011-05-19T14:06:33</LastModified>
<AllocationsList>
<Allocations>
<Custom1>North America</Custom1>
<Custom2>West</Custom2>
<Custom3>Oregon</Custom3>
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<AllocationKey>ngYn5SB4OUQfJtTrUBq94qWUuDk8g6fo$s</AllocationKey>
<Percentage>50.00000000%</Percentage>
<AccountCode1>MEAL_BRKFST</AccountCode1>
<AccountCode2 />
</Allocations>
<Allocations>
<Custom1>North America</Custom1>
<Custom2>West</Custom2>
<Custom3>Washington</Custom3>
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<AllocationKey>ngYn5SB4OUX$pWN0Y6bkzFZZhdQ2PJ$pc6b</AllocationKey>
<Percentage>50.00000000%</Percentage>
<AccountCode1>MEAL_BRKFST</AccountCode1>
<AccountCode />
</Allocations>
</AllocationsList>
</ItemizationEntryDetails>
</ItemizationsList>
<Allocations />
<AttendeeDetails>
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<AttendeeType>SYSEMP</AttendeeType>
<FirstName>Chris</FirstName>
<LastName>Miller</LastName>
<Company />
<ExternalId />
<HasExceptionsPrevYear>N</HasExceptionsPrevYear>
<HasExceptionsYtd>N</HasExceptionsYtd>
<IsDeleted>N</IsDeleted>
<OwnerEmpName>Miller, Chris</OwnerEmpName>
<Title />
<TotalAmountPrevYear>0.00000000</TotalAmountPrevYear>
<TotalAmountYtd>0.00000000</TotalAmountYtd>
<VersionNumber>1</VersionNumber>
<AttendeeKey>njxM6iDZutaiGWiqbak$sEciMQPevMSInD</AttendeeKey>
</AttendeeDetails>
<AttendeeDetails>
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<AttendeeType>BUSGUEST</AttendeeType>
<FirstName>Pat</FirstName>
<LastName>Davis</LastName>
<Company>Medico</Company>
<ExternalId />
<HasExceptionsPrevYear>N</HasExceptionsPrevYear>
<HasExceptionsYtd>N</HasExceptionsYtd>
<IsDeleted>N</IsDeleted>
<OwnerEmpName>Miller, Chris</OwnerEmpName>
<Title>Finance Manager</Title>
<TotalAmountPrevYear>0.00000000</TotalAmountPrevYear>
<TotalAmountYtd>0.00000000</TotalAmountYtd>
<VersionNumber>1</VersionNumber>
<AttendeeKey>njxM6iDZpwahAX2jt$pdRQ1etD1lNzfW83</AttendeeKey>
</AttendeeDetails>
</ExpenseEntry>
<ExpenseEntry>
<ReceiptRequired>N</ReceiptRequired>
<ImageRequired>Y</ImageRequired>
<EreceiptId />
<OrgUnit1 />
<OrgUnit2 />
<OrgUnit3 />
<OrgUnit4 />
<OrgUnit5 />
<OrgUnit6 />
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<Custom21 />
<Custom22 />
<Custom23 />
<Custom24 />
<Custom25 />
<Custom26 />
<Custom27 />
<Custom28 />
<Custom29 />
<Custom30 />
<Custom31 />
<Custom32 />
<Custom33 />
<Custom34 />
<Custom35 />
<Custom36 />
<Custom37 />
<Custom38 />
<Custom39 />
<Custom40 />
<RpeKey>nfUEGTNhWxbQmRXziCxZr2FNJmJWOcx0G</RpeKey>
<RptKey>nbe1LDA99RdTx0fUEuZiYd5WW8afkjew$p</RptKey>
<ExpKey>TRDSH</ExpKey>
<FormKey>nnamf5z0cLe4MHs53YwSIjwY0uP8kby5p</FormKey>
<ReceiptImageId>6EA8D791D82231349763EFCBC1822318</ReceiptImageId>
<ExpName>PARKING</ExpName>
<HasVat>N</HasVat>
<ExchangeRate>1.00000000000000</ExchangeRate>
<TransactionAmount>14.00000000</TransactionAmount>
<PostedAmount>14.00000000</PostedAmount>
<ApprovedAmount>14.00000000</ApprovedAmount>
<TransactionCurrencyName>US, Dollar</TransactionCurrencyName>
<VendorDescription>Saf-T-Park</VendorDescription>
<LocationName />
<LocationSubdivision />
<LocationCountry />
<SpendCategory>Transportation</SpendCategory>
<HasComments>N</HasComments>
<CommentCount>0</CommentCount>
<PaymentTypeKey>CASH</PaymentTypeKey>
<IsItemized>N</IsItemized>
<HasExceptions>N</HasExceptions>
<IsPersonal>N</IsPersonal>
<HasAttendees>N</HasAttendees>
<HasAllocation>N</HasAllocation>
<IsCreditCardCharge>N</IsCreditCardCharge>
<AttendeeCount>0</AttendeeCount>
<IsPersonalCardCharge>N</IsPersonalCardCharge>
<TransactionDate>2011-05-19T00:00:00</TransactionDate>
<LastModifiedDate>2011-05-26T20:22:03</LastModifiedDate>
<ItemizationList />
<Allocations>
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<AccountCode1>PARKING</AccountCode1>
<AccountCode2 />
<allocKey>ki7UU3hd447dlKuCVH6D7Sla83Di4kl</allocKey>
<Percentage>100.00000000%</Percentage>
</Allocations>
</ExpenseEntry>
</Entries>
</ReportDetails>
Locations v1.1
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
NOTE: Find the newer version 3.0 here
The valid city location codes in Concur. These location codes are used in the Post requests for the Expense Report service, when the City field is provided/required. The location codes vary by client, and cannot be used across multiple clients.
URI
https://www.concursolutions.com/api/expense/expensereport/v1.1/Locations
Get a list of locations
Retrieves a list of valid city location codes.
Request
Parameters
| Parameter | Required/Optional | Description |
|---|---|---|
city={_searchstring_} |
Required | The city name. The system will return all values with city names that begin with the supplied name. The city name value is not case sensitive. The value can contain the * wildcard. This wildcard matches any number of characters. For example, Locations?city=old*b_o will match the city name "Old Saybrook" |
Example
https://www.concursolutions.com/api/expense/expensereport/v1.1/Locations?city=Redmond
Headers
- Authorization - Required. Authorization header with OAuth token for valid Concur user.
- Content-Type - application/xml
Response
Content types
application/xml
Payload
This request will return a LocationsList parent element with a Location parent element for each location with a City Name that contains the search text. The Location parent element contains the following child elements.
Location elements
| Element | Description |
|---|---|
| Name | The city name. |
| Country | The country name for the location. |
| State | The state/province name for the location. Empty if there is no corresponding state/province. |
| LocationID | The unique key for the location. This value is required when posting data in the City element. |
Examples
XML example request
GET https://www.concursolutions.com/api/expense/expensereport/v1.1/Locations?city={_searchstring_} HTTP/1.1
Authorization: OAuth {access token}
XML example of successful response
HTTP/1.1 200 OK
Content-Type: application/xml
<LocationList xmlns="http://www.concursolutions.com/api/expense/expensereport/2011/03"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Location>
<Country>UNITED STATES</Country>
<LocationID>nXipdPDzr4oCPylSOd91NQqQ$sqmnQrQxR</LocationID>
<Name>Redmond</Name>
<State>Washington</State>
</Location>
<Location>
<Country>UNITED STATES</Country>
<LocationID>8WWeksu7dEoHlsiIE$28kkj3ED8swhgGgye</LocationID>
<Name>Redmond</Name>
<State>Oregon</State>
</Location>
<Location>
<Country>UNITED STATES</Country>
<LocationID>Oe11hKEi$lslPncYAe2k2h7s67sdkkLEigUIF$</LocationID>
<Name>Redmond</Name>
<State>Utah</State>
</Location>
</LocationList>
Reports v2
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
NOTE: Find the newer version 3.0 here.
The expense reports in Concur.
URI
https://www.concursolutions.com/api/expense/expensereport/v2.0/Report
GET List of Reports
The Get List of Reports version 2.0 endpoint can be used to get a list of reports for an entire company.
Request
Retrieves a list of up to 1000 reports to be used in financial and accounting system integration. This endpoint can be used to get a list of reports for the entire company.
Developers that are creating financial system integration may want to use the following search terms to get sets of reports ready for payment from Concur.
- The BatchID search term specifies the payment batch that the reports are included in. The search term returns all reports included in the specified batch, regardless of time or user. This search term is used with Concur clients who have the Standard Expense and Concurforce products.
- The JobKey search term specifies the accounting extract that the reports are included in. The search term returns all reports included in the specified extract job or batch, regardless of time or user. This search term is used with Concur clients who have the Professional and Premium Expense products.
Developers can also use one or more of the following search terms to find reports.
- The HasAttendees search term returns reports that have one or more expense entries with associated attendees.
- The Status search term specifies which report payment or approval status to return. If no Status value is sent, the default Status of Active will be used.
- The PaymentTypeID search term specifies the payment method for the report entries. The report must have at least one entry with the specified payment type. The possible payment types are returned in the PaymentTypeID element by the Get Expense Group Configuration endpoint.
- The ReportCurrency search term returns all reports with the specified reimbursement currency.
- The ReimbursementMethod search term returns reports that are set to be paid by the specified reimbursement method.
- The ReportCountry search term specifies the country indicated on the report.
- The LoginID search term specifies a report owner that is not the OAuth Consumer.
- The ModifiedAfterDate or ModifiedBeforeDate search terms return reports modified after or before a certain date and time.
Headers
- Authorization - Required Authorization header with OAuth token for valid Concur user. The OAuth consumer must have one of the following user roles in Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. These roles allow the user to manage data for the entire company
- Content-Type -
application/xml
Parameters
| Parameter | Description |
|---|---|
| BatchID | The BatchID identifies which payment batch the reports are included in. The BatchID value is returned in the BatchID element in the Response of the Get Payment Batch List endpoint. This search term is used with Concur clients who have the Standard Expense and Concurforce products. |
| HasAttendees | The HasAttendees query parameter returns reports that have one or more expense entries with attendees. The HasAttendees parameter supports the true value only. |
| Job Key | The Jobkey identifies which accounting extract or payment batch the reports are included in. The Jobkey value is returned in the id element in the Response of the Post Extract Job Request endpoint, or the jobkey element in the Response of the Post Payment Batch Close endpoint. The View value, if provided, is ignored. This search term is used with Concur clients who have the Professional and Premium Expense products. |
| Status | The Status value is designed to be used when retrieving reports for the entire company. It can be used only by OAuth consumers with the Web Services Admin role in Concur. If a request is sent by the Web Services Admin that does not contain a Status value, the Active status will be used. The possible status values are: |
| ReportCurrency | The ReportCurrency identifies the reimbursement currency of the report. This value matches the reimbursement currency of the user who submitted the report. Format: 3-letter ISO 4217 currency code. Example: USD |
| PaymentTypeID | The PaymentTypeID identifies the payment method for entries in the report. At least one entry in the report must have the specified payment type for the report to appear in the list. The possible payment types are returned in the PaymentTypeID element by the Get Expense Group Configuration function. The Payment Type Name of Cash signifies that the employee will be reimbursed directly for the expense. |
| ReimbursementMethod | The ReimbursementMethod identifies the process that the report will be reimbursed with. When using the Reimbursement Method search term, it is recommended to also use the PaymentTypeID search term, where the Payment Type Name = Cash. While it's not required to use Payment Type Name = Cash, doing so delivers results that are relevant for employee reimbursement. The possible ReimbursementMethod values are listed below. |
| Report Country | The Report Country search term returns all reports for the specified country. Format: The 2-letter ISO 3166-1 alpha-2 country code for report's country. Example: US |
| LoginID | The LoginID is the Concur login for a report owner that is not the OAuth consumer. This limits the response to reports owned by the specified user. |
| ModifiedAfterDate | This returns reports including their associated dependents (entries, itemizations, allocations, and attendees) that were modified after the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time (if desired) should be in UTC. The format is: YYYY-MM-DDThh:mm:ss |
| ModifiedBeforeDate | This returns reports including their associated dependents (entries, itemizations, allocations, and attendees) that were modified before the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time (if desired) should be in UTC. The format is: YYYY-MM-DDThh:mm:ss |
Status Enum
| Value | Description |
|---|---|
| ACTIVE | Returns unsubmitted and unpaid (payment status is not Paid) reports. |
| UNSUBMITTED | Returns unsubmitted reports. |
| PENDING | Returns submitted reports pending approval. |
| ACCOUNTINGREVIEW | Returns approved reports pending accounting review. These reports are waiting for the Processor to approve the report. |
| PROCESSING | Returns processed reports pending financial integration. These reports have an Approval Status of Final Approval and a Payment Status of Unpaid. |
| INTEGRATED | Returns reports with financial integration completed. These reports have a Payment Status of Paid. |
| PENDINGEXTERNALVALIDATION | Returns reports that are at the Pending External Validation workflow step. This workflow step can be added after report submission and before the report is extracted for payment. |
| PAYMENTCONFIRMED | Returns reports with confirmed payments. These reports have a Payment Status of Payment Confirmed. |
Reimbursement MethodEnum
| Value | Description |
|---|---|
| ADPPAY | ADP Payroll (via EPIP file) |
| APCHECK | Company Check (via Accounts Payable) |
| CNQRPAY | Expense Pay by Concur |
| PMTSERV | Other reimbursement method |
NOTE: The ReimbursementMethod search term is not available for Concur Premier- Professional and Premium clients.
XML Example Request by Status
GET https://www.concursolutions.com/api/expense/expensereport/v2.0/Reports/?status=PROCESSING HTTP/1.1
Authorization: OAuth {access token}
XML Example Request by BatchID
GET https://www.concursolutions.com/api/expense/expensereport/v2.0/Reports/?batchid=5jj374sh$W2Lsa9y28w12 HTTP/1.1
Authorization: OAuth {access token}
XML Example Request for Reports with Attendees
GET https://www.concursolutions.com/api/expense/expenserepo/v2.0/Reports/?HasAttendees=true HTTP/1.1
Authorization: OAuth {access token}
XML Example Request by Job Key
GET https://www.concursolutions.com/api/expense/expensereport/v2.0/Reports/?jobkey=5jj374sh9y28w12 HTTP/1.1
Authorization: OAuth {access token}
XML Example Request by Report Currency
GET https://www.concursolutions.com/api/expense/expensereport/v2.0/Reports/?ReportCurrency=USD HTTP/1.1
Authorization: OAuth {access token}
XML Example Request by Payment Type ID
GET https://www.concursolutions.com/api/expense/expensereport/v2.0/Reports/?PaymentTypeID=nr74tQrD8PorkF6yvS0Sm8ZeSGsw HTTP/1.1
Authorization: OAuth {access token}
XML Example Request by Reimbursement Method and Payment Type
GET https://www.concursolutions.com/api/expense/expensereport/v2.0/Reports/?ReimbursementMethod=CNQRPAY&PaymentTypeID=nr74tQrD8PorkF6yvS0Sm8ZeSGsw HTTP/1.1
Authorization: OAuth {access token}
XML Example Request by Report Country
GET https://www.concursolutions.com/api/expense/expensereport/v2.0/Reports/?reportcountry=US HTTP/1.1
Authorization: OAuth {access token}
XML Example Request by Login ID
GET https://www.concursolutions.com/api/expense/expensereport/v2.0/Reports/?loginid=cm@example.com HTTP/1.1
Authorization: OAuth {access token}
XML Example Request by Modified Date
GET https://www.concursolutions.com/api/expense/expenserepo/v2.0/Reports/?modifiedafterdate=2012-01-01T00:00:00 HTTP/1.1
Authorization: OAuth {access token}
Response
Headers
- Content-Type -
application/xml
Payload
This request will return a ReportsList parent element with a ReportSummary child element for each report. The ReportSummary elements will have the following child elements:
| Element | Description |
|---|---|
| ReportName | The name of the report. Maximum 40 characters. |
| ReportID | The unique identifier for the report, which appears in the Concur Expense UI. Maximum 40 character varchar. |
| ReportCurrency | The 3-letter ISO 4217 currency code for the expense report currency. Maximum 3 characters. |
| ReportTotal | The total amount of the report. Maximum 23 characters. |
| ReportDate | The create date of the report. Maximum 10 characters. |
| LastComment | The text of the most recent comment on the report. |
| ReportDetailsURL | The URL to access the report details. |
| ExpenseUserLoginID | The Login ID of the user this report belongs to. Maximum 128 characters. |
| ApproverLoginID | The Login ID of the user's expense approver. Maximum 128 characters. |
| EmployeeName | The name of the expense report owner. Maximum 66 characters. |
| ApprovalStatus | The report's approval status, in the OAuth consumer's language. |
| PaymentStatus | The report's payment status, in the OAuth consumer's language. |
| ApprovalURL | The URL the user can use to log in to Concur to approve the report. This element appears when requesting the TOAPPROVE view, and does not appear when using the Jobkey or BatchID search terms |
NOTE: The ApprovalURL provides a link to Expense that can be used with SSO. The link can be put into a browser window, then the approver is automatically logged into Expense and the expense report opens if:
- The company uses a Concur-supported SSO platform (and does not use the Enforce option) and...
- The approver is currently on the company network or is using VPN.
Otherwise, when the approver clicks the link, the Expense login page appears. The approver logs in and follows the normal steps for approving reports.
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
<ReportsList
xmlns="http://www.concursolutions.com/api/expense/expensereport/2012/06">
<ReportSummary>
<ReportName>Client Meeting</ReportName>
<ReportId>J20sh19D8lW2h8Dhs490ie</ReportId>
<ReportTotal>175.23000000</ReportTotal>
<ReportCurrency>USD</ReportCurrency>
<ReportDate>2012-07-12T19:22:35</ReportDate>
<LastComment>Dinner and drinks</LastComment>
<Report-Full-Details-Url>https://www.concursolutions.com/api/expense/expensereport/v2.0/report/J20sh19D8lW2h8Dhs490ie</Report-Full-Details-Url>
<ExpenseUserLoginID>cmiller@example.com</ExpenseUserLoginID>
<ApproverLoginID>tbrown@example.com</ApproverLoginID>
<EmployeeName>Chris Miller</EmployeeName>
<ApprovalStatus>Final Approval</ApprovalStatus>
<PaymentStatus>Unpaid</PaymentStatus>
</ReportSummary>
<ReportSummary>
<ReportName>Trip to Seattle</ReportName>
<ReportId>k1jDJ82H2h9as826h8hh2lk</ReportId>
<ReportTotal>1212.72000000</ReportTotal>
<ReportCurrency>USD</ReportCurrency>
<ReportDate>2012-07-17T08:11:56</ReportDate>
<LastComment></LastComment>
<Report-Full-Details-Url>https://www.concursolutions.com/api/expense/expensereport/v2.0/report/k1jDJ82H2h9as826h8hh2lk</Report-Full-Details-Url>
<ExpenseUserLoginID>tbrown@example.com</ExpenseUserLoginID>
<ApproverLoginID>pdavis@example.com</ApproverLoginID>
<EmployeeName>Terry Brown</EmployeeName>
<ApprovalStatus>Final Approval</ApprovalStatus>
<PaymentStatus>Unpaid</PaymentStatus>
</ReportSummary>
</ReportsList>
Get Report Details Request
Retrieves the full set of information for the report. Includes the Report Header, Entry, Attendee, Itemization and Allocation details. NOTE: Some elements will appear only if the OAuth consumer has the Web Services Admin role. These include: The ReportKey element, the employee's credit card information, and the employee's bank account information, VAT information, Journal entries. Connectors that utilize this information go through a review process with Concur that includes verification of secure data handling.
Parameters
| Parameter | Description |
|---|---|
| {reportId} | Required The identifier for the desired report. Example: https://www.concursolutions.com/api/expense/expensereport/v2.0/report/{reportId} URI Source: The ReportId is returned in the ReportId element of the Get List of Reports function. |
Headers
- Authorization - Authorization header with OAuth token for valid Concur user. The OAuth consumer must have one of the following user roles in Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. These roles allow the user to manage data for the entire company.
- Content-Type -
application/xml
XML Example Request
GET https://www.concursolutions.com/api/expense/expensereport/v2.0/report/n6ujbuLd1Arwe45lT7As3ThJYJf2dAsrrEW HTTP/1.1
Authorization: OAuth {access token}
Get Report Details Response
Headers
- Content-Type -
application/xml
Payload
This request will return a ReportDetails parent element with the following child elements:
| Element | Description |
|---|---|
| UserLoginID | The user ID of the report owner. Maximum 128 characters. |
| EmployeeName | The name of the employee who created the report. Maximum 66 characters. |
| ReportID | The unique identifier for the report, which appears in the Concur Expense UI. Maximum 32 character varchar. |
| ReportKey | The unencrypted unique identifier for the report, that appears on the report header. The element appears only if the OAuth consumer has the Web Services Admin role in Concur. Maximum 48 characters. |
| ReportName | The name of the report. Maximum 40 characters. Purpose The information from the Business Purpose field. |
| ReportDate | The date from the report header. Format: YYYY-MM-DDThh:mm:ss |
| CreationDate | The date the report was created. Format: YYYY-MM-DDThh:mm:ss |
| SubmitDate | The date the report was submitted. Maximum 10 characters. |
| PaidDate | The date the report was extracted for payment. This element has an attribute named i:nil. If the value for this element is null, the i:nil attribute will be set to true. Format: YYYY-MM-DDThh:mm:ss |
| CurrencyCode | The 3-letter ISO 4217 currency code for the expense report currency. The expense report currency is defined as the report creator's default reimbursement currency. |
| ReportTotal | The total amount of the report. Maximum 23 characters. |
| PersonalExpenses | The total amount of expenses marked as personal. Maximum 23 characters. |
| AmountDueEmployee | The total amount due to the employee for the report. Maximum 23 characters. |
| AmountDueCompanyCard | The total amount due to the company card for the report. Maximum 23 characters. |
| TotalClaimedAmount | The total amount of all non-personal expenses in the report. Maximum 23 characters. |
| TotalApprovedAmount | The total amount of approved expenses in the report. Maximum 23 characters. |
| ApprovalStatusCode | The approval status code for the report. |
| ApprovalStatusName | The approval status name for the report. |
| PaymentStatusCode | The unique identifier for the payment status of the report. |
| PaymentStatusName | The payment status of the report. |
| OrgUnit1 through OrgUnit6 | The details from the Org Unit custom fields. These may not have data, depending on configuration. Maximum 48 characters for each field. |
| Custom1 through Custom20 | The details from the Custom fields. These may not have data, depending on configuration. If report owner information is stored in these fields, it may be outdated. Refer to the ReportOwner parent element for the current owner information. The custom fields may have the following child elements: Type (The custom field type. Will be one of the following: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text), Value (The value in the custom field. Maximum 48 characters.), Code (Custom list fields will include the list item code in this element.) |
| LedgerName | The name of the expense report ledger. Maximum 20 characters. |
| PolicyID | The unique identifier of the policy that applies to this report. Maximum 64 characters. |
| EverSentBack | Whether the report has ever been sent back to the employee. Format: Y/N |
| HasException | Whether the report has exceptions. Format: Y/N |
| WorkflowActionURL | The URL to post a workflow action to the report using the Post Report Workflow Action function. |
| ExpenseEntriesList | This parent element has an ExpenseEntry child element for each entry. Refer to the Expense Entry Child Elements table for more information. |
| ReportImageURL | The URL to access the image associated with the report. This URL is valid for 30 minutes after the web service call. |
| Country | The report country. Maximum 2 characters. Format: The ISO 3166-1 alpha-2 country code. Example: United States is US. |
| CountrySubdivision | The report country subdivision. Format: ISO 3166-2:2007 country subdivision. |
| ProcessingPaymentDate | The date that the report completed all approvals and was ready to be extracted for payment. Format: YYYY-MM-DD |
| ReceiptsReceived | If Y, then this report has its receipt receipt confirmed by the Expense Processor. Format: Y/N |
| ReportOwner | This parent element includes details about the employee who is the report owner. It saves the caller from calling the Get User Information function to get employee information commonly used in accounting integration. The ReportOwner element includes the most recent information about the report owner, at the time the report is requested. The ReportOwner parent element includes the following child elements: EmployeeCustom21 (The report owner's group ID. Maximum 48 characters.), EmployeeID (Employee ID often also serves as the employee's Vendor ID for AP system integrations or Payroll ID for Payroll integrations. Maximum 48 characters.), EmployeeOrgUnit1 through EmployeeOrgUnit6 (The report owner's organizational unit information. Maximum 48 characters for each field. FirstName (The report owner's first name. Maximum 32 characters.), LastName (The report owner's last name. Maximum 32 characters.), MiddleInitial (The report owner's middle initial. Maximum 1 character.), ReimbursementMethodCode (The report owner's reimbursement method code, as defined in the employee's Profile.) |
| EmployeeBankAccount | This parent element includes the bank account data found on the Bank Information page in Profile. This data is used in Payment System integrations where the payment system reimburses the employee via this bank account. The EmployeeBankAccount parent element contains the following child elements: BankNumber (The bank identification number entered on the Bank Information page. Maximum 11 characters.), BankName (The bank name entered on the Bank Information page. Maximum 48 characters.), BranchLocation (The branch location entered on the Bank Information page. Maximum 30 characters.), AccountNumber (The bank account number entered on the Bank Information page. Maximum 100 characters.), AccountName (The name on the account entered on the Bank Information page.), PostalAddressLine1 (The postal address line 1 entered on the Bank Information page. Maximum 48 characters.), PostalAddressLine2 (The postal address line 2 entered on the Bank Information page. Maximum 48 characters.), PostalAddressCity (The postal address city entered on the Bank Information page. Maximum 24 characters.), PostalAddressRegion (The postal address region entered on the Bank Information page. Maximum 24 characters.), PostalAddressCode (The postal address code entered on the Bank Information page. Maximum 20 characters.), PostalAddressCountry (The postal address country entered on the Bank Information page. Maximum 2 characters. Format: The The ISO 3166-1 alpha-2 country code. Example: United States is US.) |
Expense Entry Child Elements
| Element | Description |
|---|---|
| ReportEntryID | The ID of the report entry. Maximum 13 characters. |
| ExpenseTypeID | The expense type ID for the expense entry. Expense Type IDs are returned in the ExpKey element by the Get Expense Group Configuration endpoint. |
| ExpenseTypeName | The expense type name. Maximum 64 characters. |
| SpendCategory | The spend category specified for this expense type. Varies by client, used in reporting. |
| PaymentTypeCode | The code for the payment type. Maximum 4 characters. |
| PaymentTypeName | The name for the payment type. Maximum 80 characters. |
| TransactionDate | The date of the expense entry. Maximum 10 characters. Format: YYYY-MM-DD |
| TransactionCurrencyName | The name of the transaction currency. Example: US, Dollar |
| ExchangeRate | The exchange rate that applies to the entry. Maximum 23 characters. |
| TransactionAmount | The amount of the expense entry in the original transaction currency. Maximum 23 characters. |
| PostedAmount | The amount of the expense entry in the user's reimbursement currency. The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters. |
| ApprovedAmount | The approved amount of the expense entry in the user's reimbursement currency.The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters. |
| BusinessPurpose | The text from the Business Purpose field of the entry. Maximum 64 characters. |
| VendorDescription | The vendor name of the expense entry, which can be entered manually by the user or imported from the card transaction Merchant Name field. Maximum 64 characters. |
| LocationName | The location for the expense entry, usually the city name. |
| LocationSubdivision | The location's State, Province, or Country Subdivision. Maximum 6 characters. |
| LocationCountry | The location's Country. Maximum 2 characters. |
| OrgUnit1 through OrgUnit | The details from the Org Unit custom fields. These may not have data, depending on configuration. Maximum 48 characters for each field. |
| Custom1 through Custom40 | The details from the Custom fields. These may not have data, depending on configuration. The custom fields may have the following child elements: Type (The custom field type. Will be one of the following: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text), Value (The value in the custom field. Maximum 48 characters.), Code (Custom list fields will include the list item code in this element.) |
| FormID | The ID for the expense entry form. |
| EntryImageID | The unique identifier for the image associated with the entry. |
| HasVat | Whether the entry contains VAT data. Maximum 1 character. Format: Y/N |
| HasComments | Whether the expense entry has comments. Maximum 1 character. Format: Y/N |
| CommentCount | The number of comments associated with the expense entry. |
| IsItemized | Whether the expense entry is itemized. Maximum 1 character. Format: Y/N |
| HasExceptions | Whether the expense entry has exceptions. Maximum 1 character. Format: Y/N |
| IsPersonal | Whether the expense entry is marked as personal. Maximum 1 character. Format: Y/N |
| HasAttendees | Whether the expense entry has attendees. Maximum 1 character. Format: Y/N |
| HasAllocation | Defines the amount of allocations for the expense. Maximum 1 character. Possible values are: P, for partial allocation, F, for full allocation, or N, for no allocation. |
| IsCreditCardCharge | Whether the expense came from a credit card feed. Maximum 1 character. Format: Y/N |
| IsPersonalCardCharge | Whether the expense came from a personal card feed. Maximum 1 character. Format: Y/N |
| ReceiptRequired | Whether the original receipt is required for the entry. Maximum 1 character. Format: Y/N |
| ImageRequired | Whether a receipt image is required for the entry. Maximum 1 character. Format: Y/N |
| E-ReceiptID | The ID for the attached e-receipt, if available. |
| LastModifiedDate | The date the expense entry was last changed. Maximum 19 characters. Format: YYYY-MM-DDThh:mm:ss |
| ItemizationsList | The list of itemizations for the expense entry. This parent element will have at least one Itemization child element. If the expense entry is not itemized, the Itemization will contain the same values as the entry. If the expense entry has itemizations, there will be one Itemization child element for each itemization. Refer to the Itemization Entry Details Child Elements table for more information. NOTE: There are a few rare cases where the ItemizationsList will be null. This happens when a report entry has a payment type code that is not IBCP with offsets or CBCP and there is a Regular or Child expense entry with an Approved Amount equal to zero. The expense entry will have a Null ItemizationsList. |
| ReportEntryVendorName | Vendor name the employee selected from the Vendor list field. Maximum 64 characters. |
| ReportEntryReceiptReceived | If Y, then this entry has been marked as reviewed by a processor. Maximum 1 character. Format: Y/N |
| ReportEntryReceiptType | Maximum 1 character. One of these: T = tax receipt, R = regular receipt, N = no receipt |
| CardTransaction | This parent element includes the card transaction data found in the card transaction associated to this expense entry. This data is used in Payment System integrations where the payment system reimburses the card issuer for the indicated card account. Refer to the Card Transaction Child Elements field. |
| ExpensePay | Whether the entry was paid using the Expense Pay service. This element have a value if the report has reached the Processing Payment workflow step. Format: Yes/No |
Itemization Entry Details Child Elements
| Element | Description |
|---|---|
| ItemType | The type of itemization. If the expense entry does not have any itemizations, this will be set to Regular. If the expense entry contains itemizations, each one will be set to Child. |
| ItemizationID | The unique identifier for the itemization. Maximum 19 characters. |
| ExpenseTypeID | The expense type ID for the itemization. |
| ExpenseTypeName | The expense type for the itemization. Maximum 64 characters. |
| TransactionDate | The date of the transaction. Maximum 10 characters. Format: YYYY-MM-DD |
| TransactionAmount | The amount for the itemization in the expense currency. Maximum 23 characters. |
| PostedAmount | The amount for the itemization in the user's reimbursement currency. The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters. |
| ApprovedAmount | The approved amount of the itemization in the user's reimbursement currency. The user's reimbursement currency is returned in the CrnCode element for the report. Maximum 23 characters. |
| BusinessPurpose | The business purpose field from the report header. |
| OrgUnit1 through OrgUnit6 | The details from the Org Unit custom fields. These may not have data, depending on configuration. Maximum 48 characters for each field. |
| Custom1 through Custom40 | The custom fields associated with the itemization. These may not have data, depending on your configuration. The custom fields may have the following child elements: Type (The custom field type. Will be one of the following: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text), Value (The value in the custom field. Maximum 48 characters.), Code (Custom list fields will include the list item code in this element.) |
| HasComments | Whether the itemization has comments. Maximum 1 character. Format: Y/N |
| CommentCount | The number of comments associated with the itemization. |
| IsPersonal | Whether the itemization is personal. Maximum 1 character. Format: Y/N |
| LastModified | The UTC date when the itemization was last modified. Maximum 19 characters. Format: YYYY-MM-DDThh:mm:ss |
| AttendeesList | This parent element contains one Attendee element for each associated attendee. The Attendee element contains child elements |
| AllocationsList | This parent element contains at least one Allocation element. It will contain multiple Allocation elements if there are multiple allocations for the itemization. |
Attendee List Child Elements
| Element | Description |
|---|---|
| AttendeeType | The type of attendee. Maximum 40 characters. |
| FirstName | The attendee's first name. Maximum 50 characters. |
| LastName | The attendee's last name. Maximum 132 characters. |
| Company | The attendee's company name. Maximum 150 characters. |
| Title | The attendee's title. Maximum 32 characters. |
| ExternalID | The unique identifier for the attendee, managed outside Concur. Maximum 48 characters. |
| Custom1 through Custom20 | The details from the Custom fields. These may not have data, depending on configuration. The custom fields may have the following child elements: Type (The custom field type. Will be one of the following: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text), Value (The value in the custom field. Maximum 100 characters.), Code (Custom list fields will include the list item code in this element.) |
| HasExceptionsPrevYear | Whether the attendee has exceptions in the previous year, based on yearly total limits for attendees. Maximum 1 character. Format: Y/N |
| HasExceptionsYTD | Whether the attendee has exceptions in the current year, based on yearly total limits for attendees. Maximum 1 character. Format: Y/N |
| IsDeleted | Whether the attendee is marked as deleted. Maximum 1 character. Format: Y/N |
| OwnerName | The name of the employee that owns the attendee record. |
| TotalAmountPrevYear | The total amount spent on the attendee in the previous calendar year. |
| TotalAmountYTD | The total amount spent on the attendee in the current calendar year. |
| VersionNumber | The attendee's version number. |
| AttendeeID | Attendee unique identifier within Concur. |
| AttendeeTypeCode | The unique identifier for the attendee type. |
| AttendeeOwnerID | The unique identifier for the person or system that owns the attendee. |
| CurrencyCode | The 3-letter ISO 4217 currency code for attendee related amounts. |
Allocations List Child Elements
| Element | Description |
|---|---|
| AllocationID | The unique alphanumeric identifier for the allocation. Maximum 13 characters. |
| Percentage | The percentage of the expense that is included in this allocation. Maximum 11 characters. |
| AccountCode1 | The primary accounting code assigned to the expense type associated with this allocation. Typically, expense types have only this primary account code. |
| AccountCode2 | The secondary or alternative accounting code assigned to the expense type associated with this allocation. In rare cases some expense types include this accounting code to handle special cases. One example of these special cases is when using travel allowance, where one expense would use the primary account code for the allowed amount, and the alternative account code for the overage. Another example is personal use of a company car. Refer to the Expense: Account Codes Setup Guide for more information on how Concur Expense determines which accounting codes to use. |
| Custom1 through Custom20 | The custom fields associated with the allocation. These may not have data, depending on your configuration. The custom fields may have the following child elements: Type (The custom field type. Will be one of the following: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text), Value (The value in the custom field. Maximum 48 characters.), Code (Custom list fields will include the list item code in this element.) |
| JournalEntriesList | This parent element contains at least one JournalEntry child element. It contains multiple JournalEntry elements if the allocation has multiple journal entries. The JournalEntry element contains child elements |
| VATDataList | This parent element contains one VATData element for each VAT line item. This element will be empty if there are no VAT line items. The VATData parent element contains child elements |
JournalEntry Child Elements
| Element | Description |
|---|---|
| JournalID | Unique identifier for the journal entry. |
| PayerPaymentTypeName | Payer payment type. Maximum 64 characters. One of these: Company = Company, Employee = Employee, Payment Type for the Credit Card Payment Type |
| PayerPaymentTypeCode | Payment code name for the payer. Maximum 80 characters. |
| PayeePaymentTypeName | Payee payment type. Maximum 64 characters. One of these: Company = Company, Employee = Employee Payment Type for the Credit Card Payment Type |
| PayeePaymentCode | Payment code name for the payee. Maximum 80 characters. |
| AccountCode | The account code Concur Expense determines should apply to this journal entry. For journal entries associated to an allocation, Concur Expense uses the business logic described in the Expense: Account Codes Setup Guide to determine whether the primary or secondary account code should apply. When there is no allocation associated to the journal entry, Concur Expense uses clearing account codes for Credit Card and Cash Advance for personal use of a company paid expense or a cash advance issued to an employee respectively. Maximum 48 characters. NOTE: The developer should almost always use this accounting code when creating financial transactions in financial systems. In some situations a developer may need to use the accounting codes in the Allocation parent element. |
| DebitOrCredit | Maximum 2 characters. Either: DR = Debit, CR = credit |
| Amount | Value, as credit or debit, of the amount to be exchanged between the payer and payee for this expense account code (not an absolute value) Maximum 23 characters. EXAMPLES: Value of zero, credit, or debit, as the following: 0 (Zero) "0", + (Plus / Debit) "+50.00", - (Minus / Credit) "-50.00" |
| JobRunKey | Either the unique identifier for job run for the accounting extract that processed this journal, or a static value indicating the journal was processed by Manual Pay, Expense Pay, or some other system. |
VATData Child Elements
| Element | Description |
|---|---|
| TaxName | Tax authority name. Maximum 50 characters. |
| TaxAuthorityLabel | 5-digit code that appears on the expense entry pages. Maximum 5 characters. |
| TaxTransactionAmount | Calculated tax amount for this expense in the spend currency. Maximum 23 characters. |
| TaxPostedAmount | Calculated tax amount for this expense entry in the reimbursement currency. Maximum 23 characters. |
| Source | Specifies how the tax data was derived. Maximum 4 characters. One of these: CARD= Provided from company card, USER = Entered by employee, SYST = Calculated by system, PROC = Entered by processor |
| TaxReclaimTransactionAmount | Calculated amount of tax eligible for reclaim in the spend currency. Maximum 23 characters. |
| TaxReclaimPostedAmount | Calculated amount of tax eligible for reclaim in the reimbursement currency. Maximum 23 characters. |
Card Transaction Child Elements
| Element | Description |
|---|---|
| AccountNumber | Credit card number (not encrypted) used for this expense. Maximum 255 characters. |
| CardDescription | The name on the credit card used for this expense. Maximum 255 characters. |
| CardTypeCode | Type of credit card. |
| TransactionReferenceNumber | Reference number from the credit card vendor. Maximum 64 characters. |
| TransactionCCTType | Transaction type supplied by card vendor. Maximum 3 characters. One of these: ANF = Annual Fees, CAV = Cash Advance, CCF = Cash and Check Fees, CHG = Other Bank Charges and Fees, FNC = Finance Charges, LAF = Late Fees, NSF = Insufficient Funds Check Fees, PAY = Payment, RPE = Credit Card Transaction |
| TransactionID | Calculated value assigned to this card entry during the import process. Maximum 32 characters. |
| TransactionAmount | Amount of the charge in the spend currency. Maximum 23 characters. |
| TaxAmount | Amount of tax on the transaction amount (if provided by card vendor). Maximum 23 characters. |
| TransactionAlphaCode | Currency code for the spend currency. Maximum 3 characters. Format: ISO 4217 3 digit alpha code |
| PostedAmount | Amount of the charge in the billing currency of the card. Maximum 23 characters. |
| PostedAlphaCode | Currency code for the card billing currency. Maximum 3 characters. Format: ISO 4217 3 digit alpha code |
| TransactionDate | Date the charge was made at the merchant. Maximum 10 characters. |
| PostedDate | Date the charge was posted to the credit card account. Maximum 10 characters. |
| Description | Description of the charge from the merchant. Maximum 42 characters. |
| MasterCardCode | Merchant code sent from the credit card vendor. Maximum 5 characters. |
| TransactionMerchantName | Name of the merchant. Maximum 50 characters. |
| MerchantCity | Merchant city. Maximum 40 characters. |
| MerchantState | Merchant State/Province. Maximum 32 characters. |
| MerchantCountryCode | Merchant country location code. Format: 2 digit alpha code |
| MerchantReferenceNumber | Merchant reference number passed from the merchant to the card. Maximum 15 characters. |
| ExchangeRateFromBillingToEmployeeCurrency | Currency exchange rate used between the credit card billing currency and the employee's reimbursement currency. Maximum 23 characters. |
| BillingAmount | Amount due to the company card from the employee or company (depending on who is responsible for the bill) for this detail row. Maximum 23 characters. |
XML Example of Successful Response
HTTP/1.1 200 OK
Content-Type: application/xml
<?xml version="1.0" encoding="utf-8"?>
<ReportDetails xmlns="http://www.concursolutions.com/api/expense/expensereport/2012/07" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<UserLoginID>cm@example.com</UserLoginID>
<EmployeeName>Miller, Chris</EmployeeName>
<ReportID>425FE2ADB4954FCA90CD</ReportID>
<ReportName>Client Meeting</ReportName>
<Purpose>Sales meeting</Purpose>
<ReportDate>2013-01-10T00:00:00</ReportDate>
<CreationDate>2013-01-11T01:58:20</CreationDate>
<SubmitDate>0001-01-01T00:00:00</SubmitDate>
<PaidDate i:nil="true" />
<CurrencyCode>USD</CurrencyCode>
<ReportTotal>50.00000000</ReportTotal>
<PersonalExpenses>0.00000000</PersonalExpenses>
<AmountDueEmployee>50.00000000</AmountDueEmployee>
<AmountDueCompanyCard>0.00000000</AmountDueCompanyCard>
<TotalClaimedAmount>50.00000000</TotalClaimedAmount>
<TotalApprovedAmount>50.00000000</TotalApprovedAmount>
<ApprovalStatusCode>A_NOTF</ApprovalStatusCode>
<ApprovalStatusName>Not Submitted</ApprovalStatusName>
<PaymentStatusCode>P_NOTP</PaymentStatusCode>
<PaymentStatusName>Not Paid</PaymentStatusName>
<OrgUnit1>Sales</OrgUnit1>
<OrgUnit2 />
<OrgUnit3 />
<OrgUnit4 />
<OrgUnit5 />
<OrgUnit6 />
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<LedgerName>Corporate</LedgerName>
<PolicyID>ndrF8hjzl9FtFUdfaBwVvXP$sD1vDpRKNf</PolicyID>
<EverSentBack>N</EverSentBack>
<HasException>N</HasException>
<WorkflowActionURL />
<ExpenseEntriesList>
<ExpenseEntry>
<ReportEntryID>nE0avYnILN9mHdTErNSd2pH45udFoNQ$po</ReportEntryID>
<ExpenseTypeID>BUSML</ExpenseTypeID>
<ExpenseTypeName>Business Meal (attendees)</ExpenseTypeName>
<SpendCategory>Entertainment</SpendCategory>
<PaymentTypeCode>CASH</PaymentTypeCode>
<PaymentTypeName>Cash</PaymentTypeName>
<TransactionDate>2013-01-10T00:00:00</TransactionDate>
<TransactionCurrencyName>US, Dollar</TransactionCurrencyName>
<ExchangeRate>1.00000000000000</ExchangeRate>
<TransactionAmount>50.00000000</TransactionAmount>
<PostedAmount>50.00000000</PostedAmount>
<ApprovedAmount />
<BusinessPurpose />
<VendorDescription />
<LocationName>Washington</LocationName>
<LocationSubdivision>US-DC</LocationSubdivision>
<LocationCountry>US</LocationCountry>
<OrgUnit1>Sales</OrgUnit1>
<OrgUnit2 />
<OrgUnit3 />
<OrgUnit4 />
<OrgUnit5 />
<OrgUnit6 />
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<Custom21 />
<Custom22 />
<Custom23 />
<Custom24 />
<Custom25 />
<Custom26 />
<Custom27 />
<Custom28 />
<Custom29 />
<Custom30 />
<Custom31 />
<Custom32 />
<Custom33 />
<Custom34 />
<Custom35 />
<Custom36 />
<Custom37 />
<Custom38 />
<Custom39 />
<Custom40 />
<FormID>nAaT8$puKKOhs7h2wespCW7vyyxJAJcyb5</FormID>
<EntryImageID />
<HasVat>N</HasVat>
<HasComments>N</HasComments>
<CommentCount>0</CommentCount>
<IsItemized>Y</IsItemized>
<HasExceptions>N</HasExceptions>
<IsPersonal>N</IsPersonal>
<HasAttendees>Y</HasAttendees>
<HasAllocation>N</HasAllocation>
<IsCreditCardCharge>N</IsCreditCardCharge>
<IsPersonalCardCharge>N</IsPersonalCardCharge>
<ReceiptRequired>N</ReceiptRequired>
<ImageRequired>N</ImageRequired>
<E-ReceiptID />
<LastModified>2013-01-11T01:59:52</LastModified>
<ItemizationsList>
<Itemization>
<ItemType>Regular</ItemType>
<ItemizationID>nE0avYnILN9mHdTErNSd2pH45udFoNQ$po</ItemizationID>
<ExpenseTypeID>BUSML</ExpenseTypeID>
<ExpenseTypeName>Business Meal (attendees)</ExpenseTypeName>
<TransactionDate>2013-01-10T00:00:00</TransactionDate>
<TransactionAmount>50.00000000</TransactionAmount>
<PostedAmount>50.00000000</PostedAmount>
<ApprovedAmount />
<BusinessPurpose />
<OrgUnit1>Sales</OrgUnit1>
<OrgUnit2 />
<OrgUnit3 />
<OrgUnit4 />
<OrgUnit5 />
<OrgUnit6 />
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<Custom21 />
<Custom22 />
<Custom23 />
<Custom24 />
<Custom25 />
<Custom26 />
<Custom27 />
<Custom28 />
<Custom29 />
<Custom30 />
<Custom31 />
<Custom32 />
<Custom33 />
<Custom34 />
<Custom35 />
<Custom36 />
<Custom37 />
<Custom38 />
<Custom39 />
<Custom40 />
<HasComments>N</HasComments>
<CommentCount>0</CommentCount>
<IsPersonal>N</IsPersonal>
<LastModified>2013-01-11T01:59:52</LastModified>
<AllocationsList />
<AttendeesList>
<Attendee>
<AttendeeType>BUSGUEST</AttendeeType>
<FirstName>Pat</FirstName>
<LastName>Davis</LastName>
<Company />
<Title />
<ExternalID />
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<HasExceptionsPrevYear>N</HasExceptionsPrevYear>
<HasExceptionsYTD>N</HasExceptionsYTD>
<IsDeleted>N</IsDeleted>
<OwnerEmpName>Miller, Chris</OwnerEmpName>
<TotalAmountPrevYear>0.00000000</TotalAmountPrevYear>
<TotalAmountYTD>0.00000000</TotalAmountYTD>
<VersionNumber>1</VersionNumber>
<AttendeeID>nFaAj038Hw$plfUD8be0I45wTx8$sMlTd$pP</AttendeeID>
<AttendeeTypeCode>BUSGUEST</AttendeeTypeCode>
<AttendeeOwnerID>cm@example.com</AttendeeOwnerID>
<CurrencyCode>USD</CurrencyCode>
</Attendee>
</AttendeesList>
</Itemization>
<Itemization>
<ItemType>Child</ItemType>
<ItemizationID>nE0avYnILN9g$s6lCFX0jFBWmHAiTYYf9C</ItemizationID>
<ExpenseTypeID>BRKFT</ExpenseTypeID>
<ExpenseTypeName>Breakfast</ExpenseTypeName>
<TransactionDate>2013-01-10T00:00:00</TransactionDate>
<TransactionAmount>50.00000000</TransactionAmount>
<PostedAmount>50.00000000</PostedAmount>
<ApprovedAmount>50.00000000</ApprovedAmount>
<BusinessPurpose />
<OrgUnit1>Sales</OrgUnit1>
<OrgUnit2 />
<OrgUnit3 />
<OrgUnit4 />
<OrgUnit5 />
<OrgUnit6 />
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<Custom21 />
<Custom22 />
<Custom23 />
<Custom24 />
<Custom25 />
<Custom26 />
<Custom27 />
<Custom28 />
<Custom29 />
<Custom30 />
<Custom31 />
<Custom32 />
<Custom33 />
<Custom34 />
<Custom35 />
<Custom36 />
<Custom37 />
<Custom38 />
<Custom39 />
<Custom40 />
<HasComments>N</HasComments>
<CommentCount>0</CommentCount>
<IsPersonal>N</IsPersonal>
<LastModified>2013-01-11T01:59:52</LastModified>
<AllocationsList>
<Allocation>
<AllocationID>ngYn5SB4OUXgRV6P8VgsQQr88SaKYvbqz</AllocationID>
<Percentage>100.00000000%</Percentage>
<AccountCode1>AC_BRKFT1</AccountCode1>
<AccountCode2>AC_BRKFT2</AccountCode2>
<Custom1 />
<Custom2 />
<Custom3 />
<Custom4 />
<Custom5 />
<Custom6 />
<Custom7 />
<Custom8 />
<Custom9 />
<Custom10 />
<Custom11 />
<Custom12 />
<Custom13 />
<Custom14 />
<Custom15 />
<Custom16 />
<Custom17 />
<Custom18 />
<Custom19 />
<Custom20 />
<VATDataList />
</Allocation>
</AllocationsList>
<AttendeesList />
</Itemization>
</ItemizationsList>
<UserLoginID>cm@example.com</UserLoginID>
</ExpenseEntry>
</ExpenseEntriesList>
<Country>US</Country>
<CountrySubdivision></CountrySubdivision>
<ProcessingPaymentDate></ProcessingPaymentDate>
<ReceiptsReceived>Y</ReceiptsReceived>
<ReportOwner>
<EmployeeID>cm@example.com</EmployeeID>
<LastName>Chris</LastName>
<FirstName>Miller</FirstName>
<MiddleInitial></MiddleInitial>
<EmployeeCustom21></EmployeeCustom21>
<EmployeeOrgUnit1></EmployeeOrgUnit1>
<EmployeeOrgUnit2></EmployeeOrgUnit2>
<EmployeeOrgUnit3></EmployeeOrgUnit3>
<EmployeeOrgUnit4></EmployeeOrgUnit4>
<EmployeeOrgUnit5></EmployeeOrgUnit5>
<EmployeeOrgUnit6></EmployeeOrgUnit6>
<ReimbursementMethodCode>CNQRPAY</ReimbursementMethodCode>
</ReportOwner>
</ReportDetails>
Direct Connect - Hotel v1
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Description
The Hotel Services Direct Connect provides a method for Travel users to access hotel inventory.
Once the hotel supplier has developed and certified their interface with SAP Concur, their inventory will begin appearing in hotel searches by opted-in Travel users.
This callout differs from the inbound SAP Concur web services in the following ways:
- It uses an outbound message where Travel calls a public facing API endpoint provided by the hotel supplier.
- The supplier configures and maintains the public web service interface. This guide specifies the request and response format required by SAP Concur.
Works With These SAP Concur Products
- Travel for Concur Professional/Premium
- Travel for Concur Standard
Product Restrictions
This direct connect is only available to Travel Suppliers with Hotel inventory. This direct connect is not supported in the SAP Concur mobile application.
SAP Concur products are highly configurable, and not all clients will have access to all features.
Partner developers must determine which configurations are required for their solution prior to the application review process.
Hotel Process Overview
The configuration process has the following steps:
- The Hotel Supplier creates the application on their system that will accept the requests from SAP Concur and return the appropriate responses.
- The Hotel Supplier creates the endpoint on their system that SAP Concur uses to access their inventory.
- SAP Concur creates a production company for the Hotel Supplier.
- The Hotel Supplier registers their application with SAP Concur by logging in to their production company.
- SAP Concur and the Hotel Supplier validate the application:
- The Hotel Supplier develops to the SAP Concur API and provides a test system.
- The Hotel Supplier provides the URIs and credentials for their test system to SAP Concur.
- SAP Concur sets up the vendor in the certification systems and runs a series of tests to validate the interaction between the two systems.
- Once certification passes, the Hotel supplier sends SAP Concur the production URIs and credentials.
- SAP Concur updates the production servers with the supplier's production data and does a test booking. Upon successful completion, the supplier will be live in SAP Concur for any customer to enable.
- The Travel client opts in to the Hotel callout (within the Travel Configuration) to allow their users to view and book the available inventory.
Once the configuration is complete, the callout uses the following process:
- The user searches for hotels when creating an itinerary in Travel.
- Travel sends the search request to the endpoint, using the Post HotelSearch.
- The supplier returns the properties.
- Travel sends a request for rates for some of the properties using the Post HotelAvail request. The number of properties is configurable with a current maximum of 25. More than one property may be specified in each Post HotelAvail request.
- If the user chooses to reserve a hotel room, Travel sends the Post HotelBookingRule and shows the booking and cancellation policies to the user.
- If the user accepts the policy, Travel sends the Post HotelRes.
- Travel will send Post HotelItin requests to show the user their reservation. This will happen whenever the user views their itinerary.
This callout can also be used to perform the following functions:
- Get Hotel Availabililty on a Property that was not priced in the original request
- Get the Reservation Details
- Modify the Hotel Reservation
- Cancel the Hotel Reservation
Hotel URL Structure
The hotel direct connect sends the relevant information to a URL that the travel supplier maintains.
A recommended URL structure is: https://{servername}/concur/hotel/v1/
The URL is provided by the supplier when registering the partner application.
You can use either one endpoint for all messages, or a dedicated one for each message type. In that case you have to follow these rules:
The only allowed difference between the endpoint URLs can be the message name (without OTA_ and RQ/RS):
https://{servername}/concur/hotel/v1/HotelSearch
https://{servername}/concur/hotel/v1/HotelAvail
The variable part doesn't need to be at the end:
https://{servername}/concur/hotel/HotelSearch/v1/
https://{servername}/concur/hotel/HotelAvail/v1/
Security
SAP Concur will make calls to the application connector's endpoint using SSL. During configuration, SAP Concur will connect to the application connector to validate that its hostname and access credentials are valid.
SAP Concur will not be able to connect to the application connector until a certificate signed by a Certificate Authority (CA) is installed in the application connector. If you are hosting the application connector, you will need to install the signed certificate before SAP Concur can access the connector.
SAP Concur will use Http Basic authentication. The hotel supplier will need to provide credentials that SAP Concur will send to the supplier's system for each message.
Outbound Messages
The SAP Concur outbound message format is based upon a subset of the OTA2011B hotel standard. Please refer to the Function links below for the details of the request and response format.
Please note the following general information about this format:
- All messages are stateless; there is no session and a message may come from a different Travel IP address.
- Preferred language will be sent in all requests. Hotel suppliers should make a best effort to return the users preferred language. If the users preferred language is not supported, a default language may be used instead.
- A customer identifier will be sent in all requests. The intent of this is to provide customer specific data such as hotel preference and special customer discounts or policies.
- Gzip compression is supported in requests and responses. This is controlled through the normal http gzip protocols and is not required.
- All responses will be limited to an uncompressed size of 5MB and must return within 30 seconds.
- For Production systems, the current IP address ranges are (you need to enable all of them):
- 12.129.29.0/24 and 12.129.32.0/22 (US data center)
- 84.14.175.224/27 and 62.23.83.128/25 (EU data center)
- 12.129.29.0/24 and 12.129.32.0/22 (US data center)
Functions
- Post Availability Search
- Post Booking Rule Search
- Post Hotel Search
- Post New Reservation
- Post Reservation Cancellation
- Post Reservation Update
- Post Reservation Query
Additional Information
Concur Travel Configuration
The Travel clients opt in to the Hotel inventory using a setting in the Travel Configuration. Clients must contact SAP Concur to have this setting activated.
Versioning
In most cases, new versions of Hotel Services will involve adding support for various optional nodes and attributes in the OTA standards. These changes will be backwards compatible and should not require any mandatory changes and hotel suppliers will be upgrade automatically. In the situation where a change is implemented which cannot be made backwards compatible, suppliers will need to upgrade the Hotel Services interface by and provide a new set of hotel URIs. SAP Concur recommends that the version of the interface be part of the hotel URI provided by the hotel suppliers.
Certification
The certification process will start once the vendor has completed their integration with the SAP Concur certification systems. Certification consists of running through several use cases on the certification servers and validating that in each scenario the correct response is sent. Typically, most potential issues are being worked out during the integration process and certification can be accomplished in a day or two. An example of a use case during certification would be a user searching and booking a property several months out, viewing an itinerary, changing the dates of the property, and then cancelling the reservation.
Responses and Errors
For error handling we don't use any special message. Just return the appropriate response, only replace Success node with Errors and provide some error description. Please follow the OTA Code Table for error codes. Please provide as descriptive error text as possible. It will make tracing problems lot easier on both sides.
General Requirements
Information on format or value requirements that are used in multiple endpoints is included here.
Codes
All the codes used by the Hotel Direct Connect are documented in the Hotel Direct Connect Codes.
Corporate Identifier
The corporate identifier will be passed as RequestorID node. The values will be configured on setup. Please keep the Type compliant with ID Type Codes.
<POS>
<Source ISOCountry="US" ISOCurrency="USD">
<RequestorID Type="4" ID="7777777" ID_Context="MyHotel" />
</Source>
</POS>
If a vendor requires additional identification of the client system (all calls to vendor will have the same value), you can provide a second RequestorID:
<POS>
<Source ISOCountry="US" ISOCurrency="USD">
<RequestorID Type="4" ID="7777777" ID_Context="MyHotel" />
<RequestorID Type="7" ID="8172927" ID_Context="WholeTravel" />
</Source>
</POS>
Please keep the Type compliant with ID Type Codes. The supported codes for the Requestor ID Type are: 1,2,3,4,5,7,9,13,18,21
ID Type Codes Table
| Code | Description |
|---|---|
| 1 | Customer |
| 2 | CRO (Customer Reservations Office) |
| 3 | Corporation representative |
| 4 | Company |
| 5 | Travel agency |
| 6 | Airline |
| 7 | Wholesaler |
| 8 | Car rental |
| 9 | Group |
| 10 | Hotel |
| 11 | Tour operator |
| 12 | Cruise line |
| 13 | Internet broker |
| 14 | Reservation |
| 15 | Cancellation |
| 18 | Other |
| 21 | Profile |
| 25 | Associated reservation |
| 26 | Associated itinerary reservation |
| 27 | Associated shared reservation |
| 32 | Merchant |
| 33 | Acquirer |
| 34 | Master reference |
| 35 | Purged master reference |
| 36 | Parent reference |
| 37 | Child reference |
| 38 | Linked reference |
| 39 | Contract |
| 40 | Confirmation number |
Hotel v1 - Codes
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
Hotel Direct Connect Codes
- OTA Error Codes
- FOP Codes
- Hotel Chain Codes
- AQC Codes
- Supported Languages
- ID Type Codes
- Reservation Status Types
- Preference Levels
OTA Error Codes
| Code | Description |
|---|---|
| 15 | Invalid date |
| 61 | Invalid currency code |
| 69 | Minimum stay criteria not fulfilled |
| 181 | Invalid country code |
| 243 | Invalid ARC/IATA number |
| 245 | Invalid confirmation number |
| 290 | Invalid state/province/territory code |
| 291 | Invalid zip/postal code |
| 322 | No availability |
| 323 | All not valid |
| 342 | Cancel fee may apply |
| 343 | Can't sell, file maintenance is active |
| 344 | Can't sell, record maintenance is active |
| 345 | Can't sell, inventory reconcile is active |
| 346 | Closed to arrivals |
| 347 | Company address required |
| 348 | Company or travel agent address required |
| 349 | Contact housing office |
| 350 | Credit card deposits only |
| 351 | Credit card guarantee not accepted at hotel |
| 352 | Invalid credit card type |
| 353 | Departure date is past dated |
| 354 | Deposit forfeiture and/or refund may apply |
| 355 | Deposit/guarantee due immediately |
| 356 | Invalid action/status code |
| 357 | Invalid city |
| 358 | Error convention/group code |
| 359 | Error convention/group name |
| 360 | Error entry code |
| 361 | Invalid hotel |
| 362 | Invalid number of nights |
| 363 | Invalid number of rooms |
| 364 | Error rate range |
| 365 | Error credit card |
| 366 | Error during processing, please retry |
| 367 | Invalid format |
| 368 | Error no active accommodation |
| 369 | Frequency (SMTWTFS) specified does not match date |
| 370 | Frequent guest points cannot be redeemed at this time |
| 371 | Full payment or deposit required |
| 372 | Guarantee code not accepted at this hotel |
| 373 | Guarantee required immediately |
| 374 | Guaranteed room type is not offered by this brand |
| 375 | Hotel not active |
| 376 | Hotel full check alternated |
| 377 | Invalid - max number of nights exceeded |
| 378 | Invalid - max number of rooms exceeded |
| 379 | Invalid - only one name allowed |
| 380 | Invalid arrival date for group |
| 381 | Invalid check-in date |
| 382 | Invalid check-out date |
| 383 | Invalid city code |
| 384 | Invalid client file for product type |
| 385 | Invalid confirmation or cancellation number |
| 386 | Invalid fax number |
| 387 | Invalid guarantee option |
| 388 | Invalid guaranteed room type |
| 389 | Invalid guarantee type |
| 390 | Invalid hold type |
| 391 | Invalid hold until time |
| 392 | Invalid hotel code |
| 393 | Invalid hotel location type |
| 394 | Invalid item |
| 395 | Invalid message text |
| 396 | Invalid name |
| 397 | Invalid number of adults |
| 398 | Invalid number specified |
| 399 | Invalid product type code |
| 400 | Invalid property code |
| 401 | Invalid rate requested field |
| 402 | Invalid room type |
| 403 | Invalid segment type |
| 404 | Invalid start/end date combination |
| 405 | Invalid vendor |
| 406 | Invalid for convention/group |
| 407 | Item too long |
| 408 | Last page of data already displayed |
| 409 | Maximum length of stay restriction |
| 410 | Minimum length of stay error |
| 411 | Minimum length of stay restriction |
| 412 | Modification completed |
| 413 | Modify |
| 414 | More days were specified than exist in inventory |
| 415 | Multiple hotels in same GNR not allowed |
| 416 | Multi-room/name combination invalid |
| 417 | Name change not allowed |
| 418 | Name/address missing |
| 419 | Need names |
| 420 | Need e-mail address |
| 421 | No rooms available for waitlist |
| 422 | No active accommodation found |
| 423 | No alternates defined for requested location |
| 424 | No hotels found which match this input |
| 425 | No match found |
| 426 | No rates offered for this sell request |
| 427 | No rooms available for requested dates |
| 428 | No tax information available |
| 429 | Number nights deposit exceeds stay |
| 430 | Ok |
| 431 | Out date past end date |
| 432 | Payment or deposit required, no non-guaranteed holds |
| 433 | Please book on a separate reservation |
| 434 | Product requested not in city requested |
| 435 | Property name required |
| 436 | Rate does not exist |
| 437 | Rate unavailable |
| 438 | Requested rate not available |
| 439 | Reenter |
| 440 | Request completed |
| 441 | Requested rate not available for entire stay |
| 442 | Requested rate not available for waitlist |
| 443 | Requested rate not offered at this location |
| 444 | Restrictions - limit 1 room |
| 445 | Seasonal rate change error |
| 446 | Service request not allowed |
| 447 | Unable to update - simultaneous updates |
| 448 | System error |
| 449 | Unable to add IATA nbr to existing reservation |
| 450 | Unable to process |
| 451 | Unable to retrieve client file |
| 452 | Use advance purchase arrival guarantee |
| 453 | Voucher number required |
| 454 | Wholesaler client file required |
| 455 | Wholesaler rate requires wholesaler client file |
| 456 | Work block is corrupted - cannot proceed |
| 457 | Need arrival information |
| 458 | Date outside inventory period |
| 459 | Invalid request code |
| 503 | Invalid form of deposit |
| 504 | Extra bed or crib not available |
| 505 | Invalid bed type |
| 506 | Credit card not accepted at property |
| 507 | Room type on request |
| 558 | Accounts are settled in a currency different from the quoted rate currency |
| 559 | Booking period restriction applies |
| 560 | Stay not compliant with availability restrictions |
| 561 | Loyalty program not found |
| 562 | Rate restricted |
| 563 | Closed to departure |
| 564 | Force sell restricted |
| 565 | Amount override restricted |
| 566 | Cancellation polices override restricted |
| 567 | Modification penalties apply |
| 568 | Cancellation penalties apply |
| 569 | Group booking required |
| 570 | Cannot cancel - arrival too close - call property |
| 571 | Travel agency name required |
| 572 | Company name required |
| 573 | Calendar availability is not supported by this external partner |
| 574 | Availability with pricing information is not supported by this external partner |
| 575 | Closed restriction |
| 730 | Invalid room type for requested hotel |
| 731 | Room type discontinued at this hotel |
| 732 | Invalid room type for rate requested |
| 733 | Restricted |
| 734 | Invalid corporate number for guarantee |
| 735 | Cancel hotel segments just booked, end and rebook |
| 736 | Address required for guarantee |
| 737 | System restricted |
| 738 | Form of deposit required for guarantee |
| 739 | Deposit not accepted within 72 hours |
| 740 | Guarantee required after 6pm arrival |
| 741 | Hotel requires guarantee |
| 742 | Corporate ID required |
| 743 | Invalid message length |
| 744 | Invalid field length |
| 745 | Invalid field ID |
| 746 | Name or frequent guest number required |
| 747 | Invalid frequent guest number - numeric only |
| 748 | Invalid corporate ID |
| 749 | Invalid address format |
| 750 | Invalid supplemental information |
| 751 | Adult rollaway number exceeds limit |
| 752 | Child rollaway number exceeds limit |
| 753 | Crib number exceeds limit |
| 754 | Extra adult number exceeds limit |
| 755 | Extra child number exceeds limit |
| 756 | IT number invalid |
| 757 | Unable to retrieve guest name record |
| 758 | Link process shut off |
| 759 | Confo nbr not received on modify, cancel or ignore |
| 760 | Must cancel/rebook property change |
| 761 | Frequent guest number cannot be changed |
| 762 | Corporate ID cannot be changed |
| 763 | Cannot modify name when frequent guest number present |
| 764 | Guest name may not be deleted |
| 765 | Phone may not be deleted |
| 766 | Advance deposit required for this hotel |
| 767 | Invalid room stay index |
| 768 | Inconsistent status |
| 769 | Only first reservation processed |
| 770 | Required data missing: reservation holder |
| 772 | Hotel geo-coding not yet available for country requested |
| 773 | Invalid length of parameter for search by address |
| 774 | Invalid format for search by address |
| 775 | Nothing found for requested criteria |
| 776 | Invalid length of parameter for search by availability status |
| 777 | Invalid format for search on availability status |
| 778 | No available or on request rooms found use search on all availability status |
| 779 | No available rooms found use search on all availability status |
| 780 | Invalid length of parameter for search by rate range |
| 781 | Invalid format for search by rate range |
| 782 | Rate exceeds maximum allowed for search by rate range |
| 783 | Room or rate not found |
| 784 | Time out Ð Please modify your request |
| 785 | Invalid length of parameter for search by distance |
| 786 | Invalid distance, maximum is 300 |
| 787 | Search by distance does not contain a distance measure |
| 788 | Invalid format for search by distance |
| 789 | Hotel geo-coding not yet available for area requested |
| 790 | No properties found for reference point / distance requested |
| 791 | Search by distance and search by area code are mutually exclusive |
| 792 | Automatic search by distance ignored |
| 793 | Invalid Ð Use city code or search by reference point option |
| 794 | More hotels possible without automatic search by distance |
| 795 | No similar name found, see associated cities. More hotels possible without automatic search by distance option. |
| 796 | No match for reference point name option. Automatic search by distance ignored. |
| 797 | Geo-Coding not available for country requested automatic search by distance ignored |
| 798 | Geo-Coding not available for area requested automatic search by distance ignored |
| 799 | Invalid length of parameter for search by facilities |
| 800 | Invalid format for search by facilities |
| 801 | Invalid facility code requested |
| 802 | Invalid length of parameter for search by fire safety facilities |
| 803 | Invalid format for search by fire safety facilities |
| 804 | Invalid fire safety facility code requested |
| 805 | Invalid length of parameter for search by hotel category |
| 806 | Invalid format for search by hotel category |
| 807 | Invalid hotel category requested |
| 808 | Invalid length of parameter for search by hotel name |
| 809 | No similar name found see also associated cities |
| 810 | Invalid length of parameter for search by location |
| 811 | Nothing found for requested city |
| 812 | Location requested not in the system |
| 813 | Invalid length of parameter for search by phone number |
| 814 | Invalid format for search by phone number |
| 815 | Invalid length of parameter for search by reference point |
| 816 | Invalid format for search by reference point |
| 817 | Search by reference point and search by area are mutually exclusive |
| 818 | Automatic search by area ignored |
| 819 | Specify category in search by reference point or make a search for all reference point categories. |
| 820 | Invalid length of parameter for search by third party rating |
| 821 | Invalid format for search by third party rating |
| 822 | Invalid third party rating requested |
| 823 | Invalid length of parameter for search by transportation |
| 824 | Invalid format for search by transportation |
| 825 | Invalid transportation requested |
| 826 | Maximum number of transportation types is 3 |
| 827 | Invalid length of parameter for search by zip code |
| 828 | Invalid area requested |
| 829 | Area identified can not be used twice |
| 830 | Invalid length of parameter for search by city |
| 831 | Invalid format for search by foreign currency |
| 832 | Invalid length of parameter for search by foreign currency |
| 833 | Invalid format for search by foreign currency |
| 834 | Search by lowest rate and search by biased display are mutually exclusive |
| 835 | Search by lowest rate and search by travel choice are mutually exclusive |
| 836 | Search by lowest rate and search by hotel name with ordering are mutually exclusive |
| 837 | Search by lowest rate and search by availability status are mutually exclusive |
| 838 | Invalid number of rooms in search by multiple identical room criteria |
| 839 | Invalid length of parameter for search by special rate |
| 840 | Duplicated rate codes |
| 841 | No available or on request rooms found, please use search on all availability status |
| 842 | Rate not loaded |
| 843 | Other rates available |
| 844 | Invalid length of parameter for search by hotel chain |
| 845 | Invalid number of hotel chain requested |
| 846 | Invalid format for search by hotel chain |
| 847 | Search by hotel chain and access qualifiers are mutually exclusive |
| 848 | Invalid type of access requested |
| 849 | Invalid number of access type requested |
| 850 | Non-existent service type |
| 851 | Non-existent service id |
| 852 | Invalid children ages |
| 853 | The feature penalty generation failed |
| 854 | Booking allotment blocking failed |
| 855 | Customer creation not authorized |
| 856 | Extra meal price information changed |
| 857 | Invalid extra meal |
| 858 | Change of commission not authorized |
| 859 | Invalid commission value |
| 860 | Passenger details error |
| 861 | No exact match for reference point name - use reference point list message |
| 864 | Special rate is required/missing |
FOP Codes
| Code | Description |
|---|---|
| AX | American Express |
| DC | Diner's Club |
| DS | Discover |
| CA | MasterCard |
| VI | Visa |
| CB | Carte Blanche |
| ER | Enroute |
| TP | Universal Air Travel |
| JC | JCB |
| AA | American Airlines |
| DL | Delta Equity |
| NW | Northwest Airlines |
| TW | TWA Getaway |
| UC | United Travel Card |
| UA | United Credit Card |
| EC | EuroCard |
| CP | Canadian Airlines |
| AS | Alaska Air Barter |
| PO | Purchase Order |
| AWRDCR | Award Credit |
| DB | Debit |
| PP | This code indicates that the payment is through a deposit account/prepaid account/agency invoice. Only available if the Deposit Account ID field is filled out for the travel configuration. |
Hotel Chain Codes
| Code | Description |
|---|---|
| 6C | Intercontinental Hotels Group |
| CW | Carlson Brands (All) |
| EC | Choice Brands |
| EH | Hilton (All) |
| EM | Marriott (All) |
| LQ | La Quinta Inns |
| PH | Preferred Hotels |
| SW | Starwood (All) |
| TR | Cendant Trip Rewards |
| WY | Wyndham Hotels |
| ZZ | Other/Unknown |
AQC Codes
| Code | Description |
|---|---|
| 1 | Over 21 |
| 2 | Over 65 |
| 3 | Under 2 |
| 4 | Under 12 |
| 5 | Under 17 |
| 6 | Under 21 |
| 7 | Infant |
| 8 | Child |
| 9 | Teenager |
| 10 | Adult |
| 11 | Senior |
| 12 | Additional occupant with adult |
| 13 | Additional occupant without adult |
| 14 | Free child |
| 15 | Free adult |
| 16 | Young driver |
| 17 | Younger driver |
| 18 | Under 10 |
| 19 | Junior |
Supported Languages
| Code | Description |
|---|---|
| en-us | English - American |
| en-au | English - Australian |
| en-gb | English - British |
| de | German |
| fr | French |
| fr-ca | French - Quebecois |
| es | Spanish |
| es-la | Spanish - Latin American |
| pt-br | Portuguese - Brazilian |
| nl | Dutch |
| it | Italian |
| sv | Swedish |
| ja | Japanese |
| cs | Czech |
| da | Danish |
| fi | Finnish |
| el | Greek |
| lv | Latvian |
| lt | Lithuanian |
| no | Norwegian |
| sk | Slovak |
| tr | Turkish |
ID Type Codes
| Code | Description |
|---|---|
| 1 | Customer |
| 2 | CRO (Customer Reservations Office) |
| 3 | Corporation representative |
| 4 | Company |
| 5 | Travel agency |
| 6 | Airline |
| 7 | Wholesaler |
| 8 | Car rental |
| 9 | Group |
| 10 | Hotel |
| 11 | Tour operator |
| 12 | Cruise line |
| 13 | Internet broker |
| 14 | Reservation |
| 15 | Cancellation |
| 18 | Other |
| 21 | Profile |
| 25 | Associated reservation |
| 26 | Associated itinerary reservation |
| 27 | Associated shared reservation |
| 32 | Merchant |
| 33 | Acquirer |
| 34 | Master reference |
| 35 | Purged master reference |
| 36 | Parent reference |
| 37 | Child reference |
| 38 | Linked reference |
| 39 | Contract |
| 40 | Confirmation number |
Reservation Status Types
| Code |
|---|
| Pending |
| Cancelled |
| Modified |
| Committed |
| Ignored |
| OnHold |
| Unsuccessful |
| PendingCancellation |
Preference Levels
Value|Text Value|Description ---|--- 1|company_less_preferred|- 2|company_preferred|Two silver 3|company_most_preferred|- 4|less_preferred|- 5|preferred|- 10|most_preferred|Three golden diamonds
Hotel v1 - Post an availability search
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
Description
The following request is sent when the Travel user selects a hotel and searches for availability for a date range. The response includes the list of available rooms for the supplied date range.
Request
Content type
application/xml
Encoding
UTF-8
URI
The Hotel direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:
https://{servername}/concur/hotel/v1/
The supplier determines the URI and provides it to SAP Concur to use when registering the partner application.
Authorization header
Authorization header with Basic credentials.
Request body root element
The request will contain a OTA_HotelAvailRQ parent element, containing the following attributes:
- xmlns
- EchoToken
- TimeStamp
- PrimaryLangID
- xmlns:xsi
- xsi:schemaLocation
- Version
The OTA_HotelAvailRQ parent element contains the following child elements:
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| POS | Object | The point of sale information. | |
| AvailRequestSegments | Array | This parent element contains an AvailRequestSegment element for the requested availability. |
POS child elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| Source | Object | The source of the request. This element has the following attributes: ISOCountry: The country code for the Travel user's home country. ISOCurrency: The 3-letter ISO 4217 currency code for the Travel user's currency. |
Source child elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| RequestorID | Object | The corporate identifier. If necessary, multiple RequestorID elements can be sent. This element has the following attributes: Type: The type code for the corporate identifier. Should be one of the supported ID Type Codes. ID: The corporate identifier. ID_Context: The corporate identifier context. |
AvailRequestSegment
This parent element contains an AvailRequestSegment element for the requested availability.
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| HotelSearchCriteria | Object | ||
| StayDateRange | Object | This element contains the following attributes: Start: The starting date of the requested date range. Format: YYYY-MM-DD End: The ending date of the requested date range. Format: YYYY-MM-DD |
|
| RoomStayCandidates | Array | This parent element contains the RoomStayCandidate element. This element has a Quantity attribute indicating the number of guests. Currently only one guest is supported. The RoomStayCandidate element has a GuestCounts child element containing a GuestCount element. The GuestCount element has the following attributes: AgeQualifyingCode: The value for this element should be 10, which represents an Adult guest. Count: The number of guests included in the request. |
HotelSearchCriteria child elements
| Element Name | Required/Optional | Data Type | Description |
|---|---|---|---|
| Criterion | Object | This parent element contains a HotelRef element for each hotel criterion used. Multiple criterion are compared using an OR comparison. The HotelRef element has the following attributes: ChainCode: The hotel chain code. |
XML Example Request
POST /concur/hotel/v1 HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}
<?xml version="1.0" encoding="utf-8" ?>
<OTA_HotelAvailRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" PrimaryLangID="en-us" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_HotelAvailRQ.xsd" Version="1">
<POS>
<Source ISOCountry="US" ISOCurrency="USD">
<RequestorID Type="18" ID="7777777" />
</Source>
</POS>
<AvailRequestSegments>
<AvailRequestSegment>
<HotelSearchCriteria>
<Criterion>
<HotelRef ChainCode="ZZ" HotelCode="HTL1111" />
<HotelRef ChainCode="ZZ" HotelCode="HTL2222" />
</Criterion>
</HotelSearchCriteria>
<StayDateRange Start="2012-08-15" End="2010-08-17" />
<RoomStayCandidates>
<RoomStayCandidate Quantity="1">
<GuestCounts>
<GuestCount AgeQualifyingCode="10" Count="1" />
</GuestCounts>
</RoomStayCandidate>
</RoomStayCandidates>
</AvailRequestSegment>
</AvailRequestSegments>
</OTA_HotelAvailRQ>
Response
The supplier responds to the request by returning the details of the available room.
Content Types
application/xml
Content Body
The response will include a OTA_HotelAvailRS parent element, with the following attributes:
- xmlns
- EchoToken
- TimeStamp
- xmlns:xsi
- xsi:schemaLocation
- Version
The OTA_HotelAvailRS parent element has the following child elements:
| Element Name | Required (must contain value)? | Data Type | Description |
|---|---|---|---|
| Success | N | This element is returned if the request was successful. | |
| RoomStays | Y | Array | This parent element contains a RoomStay parent element for each hotel room returned. Refer to the RoomStay child elements table for information about the child elements. |
| BasicPropertyInfo | Y | This element contains the HotelCode attribute, which contains the code for the hotel that this rate applies to. | |
| TPA_Extensions | N |
RoomStay child elements
| Element Name | Required (must contain value)? | Data Type | Description |
|---|---|---|---|
| RatePlans | Y | The room rate plan. This parent element contains the following child element: RatePlan: This element has the RatePlanCode attribute, defining the code for the room rate. |
|
| RoomRates | This parent element has a RoomRate child element. The RoomRate element has a Rates child element. | ||
| BasicPropertyInfo | Y | This element contains the HotelCode attribute, which contains the code for the hotel that this rate applies to. | |
| TPA_Extensions | N | This element contains the RequireSeriesCode child element, which has a value of true or false. This element indicates whether CVV should be queried and sent. |
Rates child elements
| Element Name | Required (must contain value)? | Data Type | Description |
|---|---|---|---|
| Rate | Object | The supplied rate for the stay. If there are multiple rates for the stay, you can provide multiple Rate elements. The first one will be displayed to the user, with the rest available through the policy popup. This element has the following attributes: EffectiveDate: The date the rate begins. ExpireDate: The date that the rate expires. |
Rate child elements
| Element Name | Required (must contain value)? | Data Type | Description |
|---|---|---|---|
| Base | The rate details per day without tax. If the rate changes, provide the first day's rate. This element has the following attributes: AmountBeforeTax: The rate amount per night before tax. AmountAfterTax: The rate amount per night after tax. CurrencyCode: The 3-letter ISO 4217 currency code for the room rate values. |
||
| RateDescription | This parent element contains the Text child element, which contains the description of the rate. |
TPA_Extensions child elements
| Element Name | Required (must contain value)? | Data Type | Description |
|---|---|---|---|
| RequireSeriesCode | This element indicates whether CVV should be queried and sent. Format: true/false | ||
| GuaranteeRequired | This element indicates whether the hotel requires a credit card deposit for this reservation. Possible values are: always: When booking this rate, user will be asked for credit card (even if a deposit account is specified). never: When booking this rate, user will not be asked for credit card (even if a deposit account is not specified). default (or not present at all): When booking this rate, user will be asked for credit card if a deposit account is not specified. |
XML Example of Successful Response
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<?xml version="1.0" encoding="utf-8" ?>
<OTA_HotelAvailRS xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_HotelAvailRS.xsd" Version="1">
<Success />
<RoomStays>
<RoomStay>
<RatePlans>
<RatePlan RatePlanCode="2222222" />
</RatePlans>
<RoomRates>
<RoomRate>
<Rates>
<Rate EffectiveDate="2012-08-15" ExpireDate="2010-08-17">
<Base AmountBeforeTax="100.00" AmountAfterTax="110.00" CurrencyCode="USD" />
<RateDescription>
<Text>CORPORATE RATE*KING</Text>
</RateDescription>
</Rate>
</Rates>
</RoomRate>
</RoomRates>
<BasicPropertyInfo HotelCode="HTL1111" />
</RoomStay>
<RoomStay>
<RatePlans>
<RatePlan RatePlanCode="3333333" />
</RatePlans>
<RoomRates>
<RoomRate>
<Rates>
<Rate EffectiveDate="2012-08-15" ExpireDate="2010-08-17">
<Base AmountBeforeTax="100.00" AmountAfterTax="110.00" CurrencyCode="USD" />
<RateDescription>
<Text>CORPORATE RATE*DOUBLE FREE INTERNET</Text>
</RateDescription>
</Rate>
</Rates>
</RoomRate>
</RoomRates>
<BasicPropertyInfo HotelCode="HTL1111" />
</RoomStay>
<RoomStay>
<RatePlans>
<RatePlan RatePlanCode="4444444" />
</RatePlans>
<RoomRates>
<RoomRate>
<Rates>
<Rate EffectiveDate="2012-08-15" ExpireDate="2010-08-17">
<Base AmountBeforeTax="100.00" AmountAfterTax="110.00" CurrencyCode="USD" />
<RateDescription>
<Text>REGULAR RATE*KING</Text>
</RateDescription>
</Rate>
</Rates>
</RoomRate>
</RoomRates>
<BasicPropertyInfo HotelCode="HTL2222" />
<TPA_Extensions>
<RequireSeriesCode>true</RequireSeriesCode>
<GuaranteeRequired>always</GuaranteeRequired>
</TPA_Extensions>
</RoomStay>
</RoomStays>
</OTA_HotelAvailRS>
Hotel v1 - Post a booking rule search
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
Description
This request is sent when the Travel user selects a rate for the hotel. The response includes the rules for the specified rate.
Request
Encoding
UTF-8
URI
The Hotel direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:
https://{servername}/concur/hotel/v1/
The supplier determines the URI and provides it to SAP Concur to use when registering the partner application.
Headers
Accept header
application/xml
Authorization header
Authorization header with Basic credentials. Required.
Request body
The request will contain a OTA_HotelBookingRuleRQ parent element, containing the following attributes:
- xmlns
- EchoToken
- TimeStamp
- PrimaryLangID
- xmlns:xsi
- xsi:schemaLocation
- Version
The OTA_HotelBookingRuleRQ parent element contains the following child elements:
| Element | Description |
|---|---|
| POS | The point of sale information. Contains a Source child element that specifies the source of the request. For information about Source element, see the Source elements table below. |
| RuleMessage | This element has the HotelCode attribute. For information about the child element of this parent element, see the StatusApplication elements table below. |
Source elements
The Source element has the following attributes:
- ISOCountry: The country code for the Travel user's home country.
- ISOCurrency: The 3-letter ISO 4217 currency code for the Travel user's currency.
The Source element contains the following element:
| Element | Description |
|---|---|
| RequestorID | The corporate identifier. If necessary, multiple RequestorID elements can be sent. This element has the following attributes: Type: The type code for the corporate identifier. Should be one of the supported ID Type Codes. ID: The corporate identifier. ID_Context: The corporate identifier context. |
StatusApplication elements
This element has the following attributes:
- Start: The start date of the request. Format: YYYY-MM-DD
- End: The end date of the request. Format: YYYY-MM-DD
- RatePlanCode: The rate plan code associated with the request.
XML Example Request
POST /concur/hotel/v1 HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}
<?xml version="1.0" encoding="UTF-8" ?>
<OTA_HotelBookingRuleRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" PrimaryLangID="en-us" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_HotelBookingRuleRQ.xsd" Version="1">
<POS>
<Source ISOCountry="US" ISOCurrency="USD">
<RequestorID Type="18" ID="7777777" />
</Source>
</POS>
<RuleMessage HotelCode="HTL1111">
<StatusApplication Start="2012-08-15" End="2010-08-17" RatePlanCode="HTL1_1" />
</RuleMessage>
</OTA_HotelBookingRuleRQ>
Response
The supplier responds to the request by returning the details of the requested rate.
Content Types
application/xml
The response will include a OTA_HotelBookingRuleRS parent element, with the following attributes:
- xmlns
- EchoToken
- TimeStamp
- xmlns:xsi
- xsi:schemaLocation
- Version
The OTA_HotelBookingRuleRS parent element contains a Success element if the request was successful. It also contains a RuleMessage element with the HotelCode and HotelName attributes. The RuleMessage element contains the following child elements:
| Element | Required (must contain value)? | Description |
|----------|---------|---------------------------------|
| StatusApplication | Y | This element contains rate details. It has the following attributes:
Start: The start date of the request. Format: YYYY-MM-DD
End: The end date of the request. Format: YYYY-MM-DD
RatePlanCode: The rate plan code for the requested rate.
The StatusApplication element contains a RoomRates element with one RoomRate child element for each rate returned. For information about this element, see the RoomRate element table below. |
| GuestCounts | Y | This parent element contains a GuestCount element with the following attributes:
AgeQualifyingCode: The value for this element should be 10, which represents an Adult guest.
Count: The number of guests included in the request. |
| BookingRules | Y | This parent element contains a BookingRule element. For information about this child element, see the BookingRule element table below. |
RoomRate element
The RoomRate element has the following attributes:
- Amount: The amount of the room rate. Provide the daily rate if you are sending multiple RoomRate elements. If you have a single rate for the entire period (one RoomRate element), send the full price of the stay including taxes. Format: 100.00
- CurrencyCode: The 3-letter ISO 4217 currency code for the rate amount.
- Start: If there are multiple daily rates, provide the start date for this rate. Format: YYYY-MM-DD
- End: If there are multiple daily rates, provide the end date for this rate. Format: YYYY-MM-DD
The RoomRate element has the following child element:
| Element | Description |
|---|---|
| RateDescription | This parent element contains a Text child element with text details of the room rate. |
BookingRule element
| Element | Description |
|---|---|
| AcceptableGuarantees | Information about acceptable guarantees. This element has an AcceptableGuarantee child element. For information about the AcceptableGuarantee element, see the AcceptableGuarantee element table below. |
| CancelPenalties | This element has the CancelPenalty child element. The CancelPenalty element has the PenaltyDescription child element, containing a Text child element with the penalty description text. |
| RequiredPaymts | This element contains the GuaranteePayment element, which has a PaymentCode attribute. The GuaranteePayment element contains the Description element, containing a Text child element with the required payment description text. |
AcceptableGuarantee element
The AcceptableGuarantee element has the GuaranteeCode attribute and the following child element:
| Element | Description |
|---|---|
| GuaranteeDescription | This element has the Text child element, containing the description of the guarantee. |
XML Example of Successful Response
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<?xml version="1.0" encoding="UTF-8" ?>
<OTA_HotelBookingRuleRS xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_HotelBookingRuleRS.xsd" Version="1">
<Success />
<RuleMessage HotelCode="HTL1111" HotelName="HOTEL1">
<StatusApplication Start="2012-08-15" End="2010-08-17" RatePlanCode="HTL1_1">
<RoomRates>
<RoomRate Amount="100.00" CurrencyCode="USD">
<RateDescription>
<Text>Standard Room</Text>
</RateDescription>
</RoomRate>
</RoomRates>
</StatusApplication>
<GuestCounts>
<GuestCount AgeQualifyingCode="10" Count="1" />
</GuestCounts>
<BookingRules>
<BookingRule>
<AcceptableGuarantees>
<AcceptableGuarantee GuaranteeCode="1">
<GuaranteeDescription>
<Text>Credit Card WILL BE CHARGED IMMEDIATELY FOR THE FULL AMOUNT of the reservation.</Text>
</GuaranteeDescription>
</AcceptableGuarantee>
</AcceptableGuarantees>
<CancelPenalties>
<CancelPenalty>
<PenaltyDescription>
<Text>The hotel imposes the following cancellation penalty: Cancellations or changes made after 11:59 PM on Jun 18, 2012 are subject to a 1 Night Room and Tax penalty. The property makes no refunds for no shows or early checkouts.</Text>
</PenaltyDescription>
</CancelPenalty>
</CancelPenalties>
<RequiredPaymts>
<GuaranteePayment PaymentCode="2">
<Description>
<Text>Prepayment required</Text>
</Description>
</GuaranteePayment>
</RequiredPaymts>
</BookingRule>
</BookingRules>
</RuleMessage>
</OTA_HotelBookingRuleRS>
Hotel v1 - Post a hotel search
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
Description
This request is sent when the Travel user searches for hotels. The response includes the list of matching hotels for the given coordinates and radius. Hotel suppliers should return properties only in this area.
Request
Encoding
UTF-8
URI
The Hotel direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:
https://{servername}/concur/hotel/v1/
The supplier determines the URI and provides it to SAP Concur to use when registering the partner application.
Request headers
Accept header
application/xml
Authorization header
Authorization header with Basic credentials. Required.
Request body
The request will contain a OTA_HotelSearchRQ parent element, containing the following attributes:
- xmlns
- EchoToken
- TimeStamp
- PrimaryLangID
- xmlns:xsi
- xsi:schemaLocation
- Version
The OTA_HotelSearchRQ parent element contains the following child elements:
| Element | Description |
|---|---|
| POS | The point of sale information. Contains a Source child element that specifies the source of the request. For information about Source element, see the Source elements table below. |
| Criteria | The search criteria provided by the customer. This parent element contains a Criterion child element. For information about this child element, see the Criterion elements table below. |
Source elements
The Source element specifies the source of the request. It has the following attributes:
- ISOCountry: The country code for the Travel user's home country.
- ISOCurrency: The 3-letter ISO 4217 currency code for the Travel user's currency.
The Source element contains the following element:
| Element | Description |
|---|---|
| RequestorID | The corporate identifier. If necessary, multiple RequestorID elements can be sent. This element has the following attributes: Type: The type code for the corporate identifier. Should be one of the supported ID Type Codes. ID: The corporate identifier. ID_Context: The corporate identifier context. |
Criterion elements
| Element | Description |
|---|---|
| Position | The hotel search center position. Position is sent all the time and is in LatLon format (degrees as float numbers). It should be used as position source for actual search. This element has two attributes: Latitude: The latitude at the center of the hotel search. Longitude: The longitude at the center of the hotel search. |
| Address | The address information for the hotel search. Optional. For information about the child elements of this parent element, see the Address elements table below. |
| RefPoint | The reference point for the search. Optional. This element has the Name attribute, containing the location city, state and country. Example: Redmond, WA, USA |
| HotelRef | The hotel information. Optional. This element can have the following attribute: HotelName: The hotel name supplied by the customer. This attribute only appears if the customer provided a name. This value should be interpreted as a "contains" style match. |
| Radius | The hotel search radius from the starting position. This element has three possible attributes: Distance: The distance to search from the defined center. DistanceMeasure: The unit of measurement to use when calculating the search radius with the Distance value. Values: Miles = M, Kilometers = K. If not included, the following attribute should be used: UnitOfMeasureCode: The code for the unit of measure. Values: Miles = 2, Kilometers = 1 NOTE: Only return hotels within this search radius. You can use a simple box search. |
| StayDateRange | The date range to search for. Contains the Start and End attributes. Format: YYYY-MM-DD |
Address elements
| Element | Description |
|---|---|
| CityName | The name of the city the user is searching in. |
| CountryName | This element has the Code attribute, containing the two character country code for the country the user is searching in. |
XML Example Request
POST /concur/hotel/v1 HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}
<OTA_HotelSearchRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" PrimaryLangID="en-us" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_HotelSearchRQ.xsd" Version="6.000">
<POS>
<Source ISOCountry="US" ISOCurrency="USD">
<RequestorID Type="4" ID="7777777" ID_Context="MyHotel" />
</Source>
</POS>
<Criteria>
<Criterion>
<Position Latitude="45.1317" Longitude="-86.1823" />
<Address>
<CityName>Empire</CityName>
<CountryName Code="US" />
</Address>
<RefPoint Name="Empire, MI, USA" />
<HotelRef HotelName="Inn" />
<Radius Distance="5" DistanceMeasure="M" />
<StayDateRange Start="2012-08-15" End="2010-08-17" />
</Criterion>
</Criteria>
</OTA_HotelSearchRQ>
Response
The supplier responds to the request by returning the list of possible search matches, with a maximum result set of 1000 results.
Content Types
application/xml
Response body
The response will include a OTA_HotelSearchRS parent element, with the following attributes:
- xmlns
- EchoToken
- TimeStamp
- xmlns:xsi
- xsi:schemaLocation
- Version
The OTA_HotelSearchRS parent element contains the following child elements:
| Element | Required (must contain value)? | Description |
|---|---|---|
| Success | N | This element is returned if the request was successful. |
| Properties | This element contains a Property parent element for each hotel property returned. For information about the child elements of this parent element, see the Property elements table below. |
Property elements
The Property element has the following attributes:
- ChainCode: If ChainCode is unknown or not available, send: ZZ
- HotelCode: This must be unique, and will be used in future requests.
- HotelName: The name of the hotel.
The Property element has the following child elements:
| Element | Description |
|---|---|
| Position | The hotel position. This element has two attributes: Latitude: The latitude of the hotel. Longitude: The longitude of the hotel. |
| Address | The address of the hotel. Optional. Provide this element if you would like the address to display in the search results. For information about the child elements of this parent element, see the Address elements table below. |
| TPA_Extensions | For information about the child elements of this parent element, see the TPA_Extensions elements table below. |
Address elements
| Element | Description |
|---|---|
| StreetNmbr | The street address of the hotel. |
| CityName | The city the hotel is in. |
| PostalCode | The postal code of the hotel. |
| CountryName | This element has the Code attribute, which contains the country code of the hotel. |
TPA_Extensions elements
| Element | Description |
|---|---|
| HotelImageURI | The link to the image associated with the hotel. A fully qualified url to the hotel image should be returned in the response. Image size must be 70 pixels wide and 72 pixels tall. Images can be no larger than 8K bytes. The image format must be gif or jpg. Images should be accessible through http and https protocols. |
| HotelPreference | This element includes the customer's preference level for the individual property. Refer to the Hotel Direct Connect Codes for the possible values. |
| GDS_InfoType | This parent element has a MasterChainCode attribute, containing the two-letter GDS code that gives access to a number of different hotel brands owned or represented by the same chain. The MasterChainCode lets Concur automatically determine what advantage card numbers to send for this hotel. Refer to the Hotel Direct Connect Codes. This parent element contains a GDS_Codes element, which contains a GDS_Code element. The GDS_Code element has the following attributes: GDS_PropertyCode: This attribute lets Concur match against other results (to display GDS and HotelService rates as one item). The most typical one is Northstar ID. If GDS_PropertyCode is provided, GDS_Name must also be provided GDS_Name: The name of the associated GDS. |
| StarRating | The number of stars the hotel is rated for. Optional. Possible values: 1-5 |
XML Example of Successful Response
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<OTA_HotelSearchRS xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_HotelSearchRS.xsd" Version="6.000">
<Success />
<Properties>
<Property ChainCode="ZZ" HotelCode="HTL1111" HotelName="HOTEL1">
<Position Latitude="45.132" Longitude="-86.1823"/>
<Address>
<StreetNmbr>123 Lake avenue</StreetNmbr>
8/33
<CityName>Empire</CityName>
<PostalCode>12345</PostalCode>
<CountryName Code="US"/>
</Address>
<TPA_Extensions>
<HotelImageURI>http://www.c.com/h/HTL1.gif</HotelImageURI>
<HotelPreference>preferred</HotelPreference>
<GDS_InfoType MasterChainCode="ZZ">
<GDS_Codes>
<GDS_Code GDS_PropertyCode="W1234567" GDS_Name="Worldspan"/>
</GDS_Codes>
</GDS_InfoType>
<StarRating>4</StarRating>
</TPA_Extensions>
</Property>
<Property ChainCode="ZZ" HotelCode="HTL2222" HotelName="HOTEL2">
<Position Latitude="45.131" Longitude="-86.1823"/>
<Address>
<StreetNmbr>124 Lake avenue</StreetNmbr>
<CityName>Empire</CityName>
<PostalCode>12345</PostalCode>
<CountryName Code="US"/>
</Address>
</Property>
<Property ChainCode="ZZ" HotelCode="HTL3333" HotelName="HOTEL3">
<Position Latitude="45.1317" Longitude="-86.182"/>
<Address>
<StreetNmbr>125 Lake avenue</StreetNmbr>
<CityName>Empire</CityName>
<PostalCode>12345</PostalCode>
<CountryName Code="US"/>
</Address>
</Property>
</Properties>
</OTA_HotelSearchRS>
Hotel v1 - Post a new reservation
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
Description
This request is sent when the Travel user creates a reservation for the supplied hotel. The response includes the reservation details.
Request
Encoding
UTF-8
URI
The Hotel direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:
https://{servername}/concur/hotel/v1/
The supplier determines the URI and provides it to SAP Concur to use when registering the partner application.
Headers
Accept header
application/xml
Authorization header
Authorization header with Basic credentials. Required.
Request body
The request will contain a OTA_HotelResRQ parent element, containing the following attributes:
- xmlns
- EchoToken
- TimeStamp
- PrimaryLangID
- xmlns:xsi
- xsi:schemaLocation
- Version
The OTA_HotelResRQ parent element contains the following child elements:
| Element | Description |
|---|---|
| POS | The point of sale information. Contains a Source child element that specifies the source of the request. For information about Source element, see the Source elements table below. |
| HotelReservations | This element has a HotelReservation child element. For information about the HotelReservation element, see the HotelReservation elements table below. |
Source elements
The Source element has the following attributes:
- ISOCountry: The country code for the Travel user's home country.
- ISOCurrency: The 3-letter ISO 4217 currency code for the Travel user's currency.
The Source element contains the following element:
| Element | Description |
|---|---|
| RequestorID | The corporate identifier. If necessary, multiple RequestorID elements can be sent. This element has the following attributes: Type: The type code for the corporate identifier. Should be one of the supported ID Type Codes. ID: The corporate identifier. ID_Context: The corporate identifier context. |
HotelReservation elements
| Element | Description |
|---|---|
| RoomStays | This parent element contains the RoomStay child element. For information about the RoomStay element, see the RoomStay elements table below. |
| ResGuests | This parent element contains the ResGuest element. The ResGuest element contains the Profiles element. The Profiles element contains the ProfileInfo element, which contains a Profile child element for each guest. The Profile child element contains the Customer parent element; for information about the Customer element, see the Customer elements table below. |
| ResGlobalInfo | This parent element contains a Memberships child element. This element contains a Membership child element with the following attributes: ProgramCode: The name of the membership program. AccountID: The account number for the membership program. |
| TPA_Extensions | This parent element contains a CustomFields element that contains a CustomField element for each custom field in the request. The CustomField elements have the following attributes: Name: The name of the custom field. Type: The type of information the custom field contains. NOTE: Some of the regular profile fields can be included in the CustomField elements. Their Type = Profile. Supported fields are: Cost Center, Employee ID, Manager, Employee Title, Organization Unit and XML Sync ID. Sharing the profile item has to be enabled for the vendor (vendor requests these values), then it can be enabled in specific travel configurations (customer wants to share the items with the vendor). |
RoomStay Request elements
| Element | Description |
|---|---|
| RoomTypes | This parent element contains the RoomType child element, with the NumberofUnits attribute indicating how many rooms of this type are included in the reservation. |
| RatePlans | This parent element contains the RatePlan child element, with the RatePlanCode attribute, specifying the rate plan code for the reservation. |
| GuestCounts | This parent element contains the GuestCount child element, with the following attributes: AgeQualifyingCode: The value for this element should be 10, which represents an Adult guest. Count: The number of guests included in the request. |
| TimeSpan | This element has the following attributes: Start: The start date of the reservation. End: The end date of the reservation. |
| Guarantee | This parent element contains the GuaranteesAccepted element. The GuaranteesAccepted element contains the GuaranteeAccepted element. This element has the GuaranteeTypeCode attribute, specifying the type of guarantee placed on the reservation. The GuaranteeAccepted parent element has a PaymentCard child element for card guarantees; for information about this child element, see the PaymentCard elements table below. |
| BasicPropertyInfo | This element contains the HotelCode attribute. |
| Comments | The comments on the reservation. This parent element contains a Comment child element for each comment associated with the reservation. |
Customer elements
| Element | Description |
|---|---|
| PersonName | This element contains the following child elements: NamePrefix: The user's name prefix. GivenName: The user's given name. Surname: The user' surname. |
| Telephone | This element has a PhoneNumber attribute containing the guests' phone number. |
| The guest's email address. | |
| Address | This parent element has the following child elements: AddressLine: The first address line. CityName: The address city. PostalCode: The address postal code. StateProv: The address state/province. CountryName: The 3-character address country name. Format: USA |
PaymentCard elements
The PaymentCard element has the following attributes:
- CardCode: The type of card.
- ExpireDate: The expiration date. Format: MMYY
- SeriesCode: The CVV value, it should be queried and passed only if hotel requires it.
The PaymentCard element has the following child elements:
| Element | Description |
|---|---|
| CardHolderName | The card holder's name. |
| Address | The billing address of the card. This parent element contains the following child elements: AddressLine: The first address line. CityName: The address city. PostalCode: The address postal code. StateProv: The address state/province. CountryName: The 2-character address country name. Format: US |
XML Example Request
POST /concur/hotel/v1 HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}
<?xml version="1.0" encoding="UTF-8" ?>
<OTA_HotelResRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" PrimaryLangID="en-us" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_HotelResRQ.xsd" Version="1">
<POS>
<Source ISOCountry="US" ISOCurrency="USD">
<RequestorID Type="18" ID="7777777" />
</Source>
</POS>
<HotelReservations>
<HotelReservation>
<RoomStays>
<RoomStay>
<RoomTypes>
<RoomType NumberOfUnits="1" />
</RoomTypes>
<RatePlans>
<RatePlan RatePlanCode="222222" />
</RatePlans>
<GuestCounts>
<GuestCount AgeQualifyingCode="10" Count="1" />
</GuestCounts>
<TimeSpan Start="2012-08-15" End="2010-08-17" />
<Guarantee>
<GuaranteesAccepted>
<GuaranteeAccepted GuaranteeTypeCode="CC">
<PaymentCard CardCode="AX" ExpireDate="1215" SeriesCode="1234">
<CardHolderName>CHRIS MILLER</CardHolderName>
<Address>
<AddressLine>18400 NE UNION HILL RD.</AddressLine>
<CityName>REDMOND</CityName>
<PostalCode>98052</PostalCode>
<StateProv>WA</StateProv>
<CountryName>US</CountryName>
</Address>
</PaymentCard>
</GuaranteeAccepted>
</GuaranteesAccepted>
</Guarantee>
<BasicPropertyInfo HotelCode="HTL1111" />
<Comments>
<Comment>NON-SMOKING</Comment>
<Comment>not close to the elevator</Comment>
</Comments>
</RoomStay>
</RoomStays>
<ResGuests>
<ResGuest>
<Profiles>
<ProfileInfo>
<Profile>
<Customer>
<PersonName>
<NamePrefix>Mr.</NamePrefix>
<GivenName>CHRIS</GivenName>
<Surname>MILLER</Surname>
</PersonName>
<Telephone PhoneNumber="212-555-1212" />
<Email>cmiller@example.com</Email>
<Address>
<AddressLine>18400 NE Union Hill Rd.</AddressLine>
<CityName>Redmond</CityName>
<PostalCode>98052</PostalCode>
<StateProv>WA</StateProv>
<CountryName>USA</CountryName>
</Address>
</Customer>
</Profile>
</ProfileInfo>
</Profiles>
</ResGuest>
</ResGuests>
<ResGlobalInfo>
<Memberships>
<Membership ProgramCode="HotelLoyaltyProgram" AccountID="987654321" />
</Memberships>
</ResGlobalInfo>
<TPA_Extensions>
<CustomFields>
<CustomField Name="OrgUnit" Type="Profile">Sales</CustomField>
<CustomField Name="XmlSyncId" Type="Profile">9293kks8drf6s8f</CustomField>
</CustomFields>
</TPA_Extensions>
</HotelReservation>
</HotelReservations>
</OTA_HotelResRQ>
Response
The supplier responds to the request by returning the details of the completed booking.
Content Types
application/xml
Response body
The response will include a OTA_HotelResRS parent element, with the following attributes:
- xmlns
- EchoToken
- ResResponseType: The reservation status.
- TimeStamp
- xmlns:xsi
- xsi:schemaLocation
- Version
The OTA_HotelResRS parent element contains the following child elements:
| Element | Required? | Description |
|---|---|---|
| Success | N | This element is returned if the request was successful. |
| HotelReservations | Y | This element has a HotelReservation child element. For information about the HotelReservation element, see the HotelReservation elements table below. |
HotelReservation elements
| Element | Description |
|---|---|
| RoomStays | This parent element contains the RoomStay child element. For information about the RoomStay element, see the RoomStay Response elements table below. |
| ResGuests | This parent element contains the ResGuest element. For information about the ResGuest element, see the ResGuest Response elements table below. |
| ResGlobalInfo | This parent element contains a HotelReservationIDs parent element, which contains a HotelReservationID child element with the ResID_Value attribute, identifying the reservation. |
| TPA_Extensions | This parent element contains a VoucherURL child element. If you need to provide some voucher or certificate of purchase, please publish it on your server and provide the URL in the VoucherURL element. |
RoomStay Response elements
| Element | Description |
|---|---|
| RoomTypes | This parent element contains the RoomType child element, with the NumberofUnits attribute indicating how many rooms of this type are included in the reservation. The RoomType parent element has the RoomDescription child element. The RoomDescription element contains the Text element describing the room. |
| RatePlans | This parent element contains the RatePlan child element, with the RatePlanCode attribute, specifying the rate plan code for the reservation. For information about the RatePlan element, see the RatePlan elements table below. |
| RoomRates | This parent element contains the RoomRate element, with a RatePlanCode attribute. The RoomRate element contains a Rates parent element, with a Rate child element for each included rate. The Rate is for each day, not the total rate. For information about the Rate element, see the Rate elements table below. |
| GuestCounts | This element contains a GuestCount element with the following attributes: AgeQualifyingCode: The value for this element should be 10, which represents an Adult guest. Count: The number of guests included in the request. |
| TimeSpan | This element has the following attributes: Start: The start date of the reservation. End: The end date of the reservation. |
| BasicPropertyInfo | This element contains the HotelCode and HotelName attributes. The BasicPropertyInfo parent element has an Address child element. For information about the Address element, see the Address elements table below. |
RatePlan elements
| Element | Description |
|---|---|
| CancelPenalties | This element contains the CancelPenalty parent element. The CancelPenalty element contains the PenaltyDescription element, with a Text child element containing the cancellation penalty text. |
| RatePlanDescription | This element contains a Text child element with the text description of the rate plan. |
Rate elements
The Rate element has the following attributes:
- EffectiveDate: The starting date for the rate.
- ExpireDate: The ending date for the rate.
The Rate element contains the following child elements:
| Element | Description |
|---|---|
| Base | The base rate amount. This element contains the following attributes: AmountAfterTax: The rate amount with all taxes included. CurrencyCode: The 3-letter ISO 4217 currency code for the rate amount. The Base element contains the Taxes child element. The Taxes element contains a Tax element for each included tax, with the following attributes: Amount: The amount of the tax. CurrencyCode: The The 3-letter ISO 4217 currency code for the tax amount. The Tax element contains a TaxDescription parent element, with a Text child element containing the tax description text. |
Address elements
| Element | Description |
|---|---|
| AddressLine | The first address line. |
| CityName | The address city. |
| PostalCode | The address postal code. |
| CountryName | The 3-character address country name. Format: USA |
ResGuest Response elements
The ResGuest response parent element contains the ProfileInfo child element. The ProfileInfo element has the Profile child element. The Profile element contains the Customer element. The Customer element contains the PersonName element. The PersonName element contains the following child elements:
| Element | Description |
|---|---|
| NamePrefix | The guest's name prefix. |
| GivenName | The guest's first name. |
| Surname | The guest's last name. |
XML Example of Successful Response
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<?xml version="1.0" encoding="utf-8" ?>
<OTA_HotelResRS
xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" ResResponseType="Committed" TimeStamp="2012-01-01T19:00:00" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_HotelResRS.xsd" Version="1">
<Success />
<HotelReservations>
<HotelReservation>
<RoomStays>
<RoomStay>
<RoomTypes>
<RoomType NumberOfUnits="1">
<RoomDescription>
<Text>Standard Room</Text>
</RoomDescription>
</RoomType>
</RoomTypes>
<RatePlans>
<RatePlan RatePlanCode="2222222">
<CancelPenalties>
<CancelPenalty>
<PenaltyDescription>
<Text>The hotel imposes the following cancellation penalty: Cancellations or changes made after 11:59 PM on Jun 18, 2012 are subject to a 1 Night Room and Tax penalty. The property makes no refunds for no shows or early checkouts.</Text>
</PenaltyDescription>
</CancelPenalty>
</CancelPenalties>
<RatePlanDescription>
<Text>Standard Room</Text>
</RatePlanDescription>
</RatePlan>
</RatePlans>
<RoomRates>
<RoomRate RatePlanCode="2222222">
<Rates>
<Rate EffectiveDate="2012-08-15" ExpireDate="2012-08-17">
<Base AmountAfterTax="100.00" CurrencyCode="USD">
<Taxes>
<Tax Amount="10.00" CurrencyCode="USD">
<TaxDescription>
<Text>VAT</Text>
</TaxDescription>
</Tax>
</Taxes>
</Base>
</Rate>
<Rate EffectiveDate="2012-08-15" ExpireDate="2012-08-15">
<Base AmountAfterTax="100.00" CurrencyCode="USD" />
</Rate>
<Rate EffectiveDate="2012-08-16" ExpireDate="2012-08-16">
<Base AmountAfterTax="110.00" CurrencyCode="USD" />
</Rate>
</Rates>
</RoomRate>
</RoomRates>
<GuestCounts>
<GuestCount AgeQualifyingCode="10" Count="1" />
</GuestCounts>
<TimeSpan Start="2012-08-15" End="2010-08-17" />
<BasicPropertyInfo HotelCode="HTL1111" HotelName="Hotel Deluxe">
<Address>
<AddressLine>123 HOTEL ST</AddressLine>
<CityName>HOTELTOWN</CityName>
<PostalCode>12344</PostalCode>
<CountryName>USA</CountryName>
</Address>
</BasicPropertyInfo>
</RoomStay>
</RoomStays>
<ResGuests>
<ResGuest>
<Profiles>
<ProfileInfo>
<Profile>
<Customer>
<PersonName>
<NamePrefix>Mr.</NamePrefix>
<GivenName>CHRIS</GivenName>
<Surname>MILLER</Surname>
</PersonName>
</Customer>
</Profile>
</ProfileInfo>
</Profiles>
</ResGuest>
</ResGuests>
<ResGlobalInfo>
<HotelReservationIDs>
<HotelReservationID ResID_Value="888000888" />
</HotelReservationIDs>
</ResGlobalInfo>
<TPA_Extensions>
<CustomFields>
<CustomField Name="OrgUnit" Type="Profile">Sales</CustomField>
<CustomField Name="XmlSyncId" Type="Profile">9293kks8drf6s8f</CustomField>
</CustomFields>
</TPA_Extensions>
</HotelReservation>
</HotelReservations>
</OTA_HotelResRS>
Hotel v1 - Post a reservation cancellation
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
Description
This request is sent when the Travel user cancels their reservation. The response includes the reservation cancellation code.
Request
Encoding
UTF-8
URI
The Hotel direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:
https://{servername}/concur/hotel/v1/
The supplier determines the URI and provides it to SAP Concur to use when registering the partner application.
Request headers
Accept header
application/xml
Authorization header
Authorization header with Basic credentials. Required.
Request body
The request will contain a OTA_CancelRQ parent element, containing the following attributes:
- CancelType: The value should be "Cancel"
- xmlns
- EchoToken
- TimeStamp
- PrimaryLangID
- xmlns:xsi
- xsi:schemaLocation
- Version
The OTA_CancelRQ parent element contains the following child elements:
| Element | Description |
|---|---|
| POS | The point of sale information. Contains a Source child element that specifies the source of the request. For information about Source element, see the Source elements table below. |
| UniqueID | This element has the following attributes: ID: The reservation identification number. Type: The type of reservation. |
Source elements
The Source element specifies the source of the request. It has the following attributes:
- ISOCountry: The country code for the Travel user's home country.
- ISOCurrency: The 3-letter ISO 4217 currency code for the Travel user's currency.
The Source element contains the following element:
| Element | Description |
|---|---|
| RequestorID | The corporate identifier. If necessary, multiple RequestorID elements can be sent. This element has the following attributes: Type: The type code for the corporate identifier. Should be one of the supported ID Type Codes. ID: The corporate identifier. ID_Context: The corporate identifier context. |
XML Example Request
POST /concur/hotel/v1 HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}
<?xml version="1.0" encoding="utf-8" ?>
<OTA_CancelRQ CancelType="Cancel" xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" PrimaryLangID="en-us" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_CancelRQ.xsd" Version="1">
<POS>
<Source ISOCountry="US" ISOCurrency="USD">
<RequestorID Type="18" ID="7777777" />
</Source>
</POS>
<UniqueID ID="888000888" Type="14" />
</OTA_CancelRQ>
Response
The supplier responds to the request by returning the details of the completed booking.
Content Types
application/xml
Response body
The response includes an OTA_CancelRS parent element with the following attributes:
- Status: The value should be "Cancelled"
- xmlns
- EchoToken
- TimeStamp
- xmlns:xsi
- xsi:schemaLocation
- Version
The OTA_CancelRS parent element contains a Success element if the request was successful. It also contains the following child elements:
| Element | Description |
|---|---|
| UniqueID | This parent element has the following attributes: ID: The ID of the cancelled reservation. Type: Any number can be supplied in this attribute. |
| CancelInfoRS | This element has a UniqueID child element with the following attributes: ID: The hotel cancellation number. Type: Value for cancellation number should be 15, confirmation number 14. |
XML Example Request
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<?xml version="1.0" encoding="utf-8" ?>
<OTA_CancelRS Status="Cancelled" xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_CancelRS.xsd" Version="1">
<Success />
<UniqueID ID="888000888" Type="14" />
<CancelInfoRS>
<UniqueID ID="1010010000" Type="14" />
</CancelInfoRS>
</OTA_CancelRS>
Hotel v1 - Post a reservation query
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
Description
This request is sent when the Travel user requests the reservation details for the supplied reservation ID. The response includes the reservation details, and is identical to the Post New Reservation response.
Request
Encoding
UTF-8
URI
The Hotel direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:
https://{servername}/concur/hotel/v1/
The supplier determines the URI and provides it to SAP Concur to use when registering the partner application.
Headers
Accept header
application/xml
Authorization header
Authorization header with Basic credentials. Required. Refer to the Security documentation for more information.
Request body
The request will contain a OTA_ReadRQ parent element, containing the following attributes:
- xmlns
- EchoToken
- TimeStamp
- PrimaryLangID
- xmlns:xsi
- xsi:schemaLocation
- Version
The OTA_ReadRQ parent element contains the following child elements:
| Element | Description |
|---|---|
| POS | The point of sale information. Contains a Source child element that specifies the source of the request. For information about Source element, see the Source elements table below. |
| ReadRequests | This element has a ReadRequest child element. For information about the ReadRequest element, see the ReadRequest elements table below. |
Source elements
The Source element has the following attributes:
- ISOCountry: The country code for the Travel user's home country.
- ISOCurrency: The 3-letter ISO 4217 currency code for the Travel user's currency.
The Source element contains the following element:
| Element | Description |
|---|---|
| RequestorID | The corporate identifier. If necessary, multiple RequestorID elements can be sent. This element has the following attributes: Type: The type code for the corporate identifier. Should be one of the supported ID Type Codes. ID: The corporate identifier. ID_Context: The corporate identifier context. |
ReadRequest elements
| Element | Description |
|---|---|
| UniqueID | This element has the following attributes: ID: The reservation identification number. Type: The type of reservation. |
| Verification | This parent element contains information that can be used to verify the owner of the reservation. For information about the Verification element, see the Verification elements table below. |
Verification elements
| Element | Description |
|---|---|
| PersonName | This parent element contains the GivenName and SurName child elements, which should match the reservation details. |
| TelephoneInfo | This element has the PhoneNumber attribute, which contains the guest telephone number. The number should match the reservation. |
XML Example Request
POST /concur/hotel/v1 HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}
<?xml version="1.0" encoding="utf-8" ?>
<OTA_ReadRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" PrimaryLangID="en-us" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_ReadRQ.xsd" Version="1">
<POS>
<Source ISOCountry="US" ISOCurrency="USD">
<RequestorID Type="18" ID="7777777" />
</Source>
</POS>
<ReadRequests>
<ReadRequest>
<UniqueID ID="888000888" Type="14" />
<Verification>
<PersonName>
<GivenName>CHRIS</GivenName>
<Surname>MILLER</Surname>
</PersonName>
<TelephoneInfo PhoneNumber="212-555-1212" />
</Verification>
</ReadRequest>
</ReadRequests>
</OTA_ReadRQ>
Response
The supplier responds to the request by returning the details of the completed booking.
Content Types
application/xml
Response body
The response is identical to the response for Post New Reservation.
Hotel v1 - Post a reservation update
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Description
NOTE: This function is not supported in the current version. Support may be returned in a future release.
This request is sent when the Travel user updates their reservation. The response includes the new reservation identifier.
Request
Encoding
UTF-8
Request URI
The Hotel direct connect sends the relevant information to a URI that the travel supplier maintains. The standard location is:
https://{servername}/concur/hotel/v1/
The URI is configured by the supplier when registering the partner application.
Headers
Accept header
application/XML
Authorization header
Authorization header with Basic credentials.
Request Body
The request will contain an OTA_HotelResModifyRQ parent element, with the following attributes:
- xmlns
- EchoToken
- TimeStamp
- PrimaryLangID
- xmlns:xsi
- xsi:schemaLocation
- Version
The OTA_HotelResModifyRQ element contains the following child elements:
| Element | Description |
|---|---|
| POS | The point of sale information. Contains a Source child element that specifies the source of the request. For information about Source element, see the Source elements table below. |
| HotelResModifies | This element has a HotelResModify child element. For more information about this child element, see the HotelResModify element table below. |
Source elements
The Source element has the following attributes:
- ISOCountry: The country code for the Travel user's home country.
- ISOCurrency: The 3-letter ISO 4217 currency code for the Travel user's currency.
The Source element contains the following element:
| Element | Description |
|---|---|
| RequestorID | The customer's identifiers. If necessary, multiple RequestorID elements can be sent. This element has the following attributes: Type: The code for the customer type. ID: The identifier for the user. |
HotelResModify element
The HotelResModify element with the following attributes:
- RoomStayReservation: Whether the reservation is for a room stay. Format: true/false.
- CreateDateTime: The time the reservation was originally created, in the hotel's local time zone.
- CreatorID: The source of the reservation.
The HotelResModify element contains the following child elements:
| Element | Description |
|---|---|
| RoomStays | This parent element contains the RoomStay element. Refer to the RoomStay Request elements table for information about child elements. |
| ResGuests | This parent element contains the ResGuest element. For more information about this child element, see the ResGuest elements table below. |
| ResGlobalInfo | This parent element contains a HotelReservationIDs child element. This element contains a HotelReservationID child element with the following attribute: ResID_Value: The reservation ID. |
RoomStay Request elements
| Element | Description |
|---|---|
| RoomTypes | This parent element contains the RoomType child element, with the NumberofUnits attribute indicating how many rooms of this type are included in the reservation. |
| RatePlans | This parent element contains the RatePlan child element, with the RatePlanCode attribute, specifying the rate plan code for the reservation. |
| GuestCounts | This parent element contains the GuestCount child element, with the following attributes: AgeQualifyingCode: The value for this element should be 10, which represents an Adult guest. Count: The number of guests included in the request. |
| TimeSpan | This element has the following attributes: Start: The start date of the reservation. End: The end date of the reservation. |
| Guarantee | This parent element contains the GuaranteesAccepted element. The GuaranteesAccepted element contains the GuaranteeAccepted element. This element has the GuaranteeTypeCode attribute, specifying the type of guarantee placed on the reservation. The GuaranteeAccepted parent element has a PaymentCard child element for card guarantees; for information about this child element, see the PaymentCard elements table below. |
| BasicPropertyInfo | This element contains the HotelCode attribute. |
| Comments | The comments on the reservation. This parent element contains a Comment child element for each comment associated with the reservation. |
ResGuest elements
The ResGuest element has the following attributes:
- ResGuestRPH: The unique identifier for the guest.
- AgeQualifyingCode: The value for this element should be 10, which represents an Adult guest.
The ResGuest element contains a Profiles child element with information about the guest's profile. The Profiles element contains the ProfileInfo child element. The ProfileInfo element has the Profile child element. The Profile element contains the Customer element. The Customer element contains the following child elements:
| Element | Description |
|---|---|
| PersonName | This element contains the following child elements: GivenName: The guest's given name. Surname: The guest's surname. |
| Telephone | This element has a PhoneNumber attribute containing the guest's phone number. |
| The guest's email address. | |
| Address | This parent element has the following child elements: AddressLine: The first address line. CityName: The address city. PostalCode: The address postal code. StateProv: The address state/province. CountryName: The 2-character address country name. Format: US |
PaymentCard elements
The PaymentCard element has the following attributes:
- CardCode: The type of card.
The PaymentCard element has the following child elements:
| Element | Description |
|---|---|
| CardHolderName | The card holder's name. |
| Address | The billing address of the card. This parent element contains the following child elements: AddressLine: The first address line. CityName: The address city. PostalCode: The address postal code. StateProv: The address state/province. CountryName: The 2-character address country name. Format: US |
XML Example Request
POST /concur/hotel/v1 HTTPS/1.1
Host: example.com
Authorization: Basic ...
Content-Type: application/xml
Content-Length: {length of content body}
<?xml version="1.0" encoding="UTF-8" ?>
<OTA_HotelResModifyRQ xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" PrimaryLangID="en-us" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_HotelResModifyRQ.xsd" Version="1">
<POS>
<Source ISOCountry="US" ISOCurrency="USD">
<RequestorID Type="18" ID="7777777" />
</Source>
</POS>
<HotelResModifies>
<HotelResModify RoomStayReservation="true" CreateDateTime="2003-03-11T17:29:00-08:00" CreatorID="Expedia">
<RoomStays>
<RoomStay>
<RoomTypes>
<RoomType NumberOfUnits="1" />
</RoomTypes>
<RatePlans>
<RatePlan RatePlanCode="2222222" />
</RatePlans>
<GuestCounts>
<GuestCount AgeQualifyingCode="10" Count="1" />
</GuestCounts>
<TimeSpan Start="2012-08-15" End="2010-08-16" />
<Guarantee>
<GuaranteesAccepted>
<GuaranteeAccepted GuaranteeTypeCode="CC">
<PaymentCard CardCode="AX"
ExpireDate="1215">
<CardHolderName>CHRIS MILLER</CardHolderName>
<Address>
<AddressLine>18400 NE UNION HILL RD.</AddressLine>
<CityName>REDMOND</CityName>
<PostalCode>98052</PostalCode>
<StateProv>WA</StateProv>
<CountryName>US</CountryName>
</Address>
</PaymentCard>
</GuaranteeAccepted>
</GuaranteesAccepted>
</Guarantee>
<BasicPropertyInfo HotelCode="HTL1111" />
</RoomStay>
</RoomStays>
<ResGuests>
<ResGuest ResGuestRPH="1" AgeQualifyingCode="10">
<Profiles>
<ProfileInfo>
<Profile>
<Customer>
<PersonName>
<GivenName>CHRIS</GivenName>
<Surname>MILLER</Surname>
</PersonName>
<Telephone PhoneNumber="212-555-1212" />
<Email>cmiller@example.com</Email>
<Address>
<AddressLine>18400 NE Union Hill Rd.</AddressLine>
<CityName>Redmond</CityName>
<PostalCode>98052</PostalCode>
<StateProv>WA</StateProv>
<CountryName>USA</CountryName>
</Address>
</Customer>
</Profile>
</ProfileInfo>
</Profiles>
</ResGuest>
</ResGuests>
<ResGlobalInfo>
<HotelReservationIDs>
<HotelReservationID ResID_Value="888000888" />
</HotelReservationIDs>
</ResGlobalInfo>
</HotelResModify>
</HotelResModifies>
</OTA_HotelResModifyRQ>
Response
The supplier responds to the request by returning an updated booking identifier.
Content Types
application/xml
Response body
The response includes an OTA_HotelResModifyRS parent element with the following attributes:
- xmlns
- EchoToken
- TimeStamp
- xmlns:xsi
- xsi:schemaLocation
- Version
The OTA_HotelResModifyRS parent element contains a Success element if the request was successful. It also contains a HotelResModifies element. The HotelResModifies element contains the HotelResModify element. The HotelResModify element contains the ResGlobalInfo child elements. The ResGlobalInfo element contains the HotelReservationIDs element. The HotelReservationIDs element contains two HotelReservationID child elements with the ResID_Value attribute containing the reservation ID. The first HotelReservationID element contains the original reservation identifier, and the second one contains the new reservation ID.
XML Example of Successful Response
HTTPS/1.1 200 OK
Content-Type: application/xml
Content-Length: {length of content body}
<?xml version="1.0" encoding="UTF-8" ?>
<OTA_HotelResModifyRS xmlns="http://www.opentravel.org/OTA/2003/05" EchoToken="ABC123" TimeStamp="2012-01-01T19:00:00" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 ../Schemas/OTA_HotelResModifyRS.xsd" Version="1">
<Success />
<HotelResModifies>
<HotelResModify>
<ResGlobalInfo>
<HotelReservationIDs>
<HotelReservationID ResID_Value="888000888" />
<HotelReservationID ResID_Value="999000999" />
</HotelReservationIDs>
</ResGlobalInfo>
</HotelResModify>
</HotelResModifies>
</OTA_HotelResModifyRS>
List Item Web Service v1
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
Description
The Concur List Item web service provides an automated solution to clients who would like to add, update or delete list items. This web service solves several business problems:
- Files are difficult to manage: The service allows clients to send the data programatically, without requiring files to be moved and managed.
- Need to work outside the Overnight Processing Period (ONP): Clients that need to make updates outside the ONP can use the List Item web service to modify their list items at any time. This allows users to quickly submit expense reports using the new values.
Works With These Concur Products
- Expense for Concur Professional/Premium
- Expense for Concur Standard
- Invoice for Concur Professional/Premium
- Invoice for Concur Standard
- Travel Request for Concur Professional/Premium
Product Restrictions
Concur products are highly configurable, and not all clients will have access to all features.
Partner developers must determine which configurations are required for their solution prior to the review process.
Existing clients can work with Concur Advantage Technical Services to create custom applications that work with their configuration.
Resources
Responses and errors
List item errors
The web service will not return a 4xx HTTP response code for a batch operation even when every item in the batch failed to be created, updated or deleted. The client must inspect the response to look for warnings or errors with individual batch items.
When there are errors with batch items, the first ten errors are returned in the
XML Response Error Codes
| Error Code | Message |
|---|---|
| 1001 | Could not find list-item-batch element |
| 1002 | Error parsing list item {ITEM} |
| 1003 | Start and end dates must be specified in pairs |
| 1004 | List item name must be specified |
| 1005 | List item name cannot be empty |
| 1006 | List item name exceeds 64 characters |
| 1010 | At least one level code must be specified |
| 1011 | Only one level code is allowed |
| 1012 | One or more level codes were skipped |
| 1013 | Invalid level1Code |
| 1014 | Invalid level2Code |
| 1015 | Invalid level3Code |
| 1016 | Invalid level4Code |
| 1017 | Invalid level5Code |
| 1018 | Invalid level6Code |
| 1019 | Invalid level7Code |
| 1020 | Invalid level8Code |
| 1021 | Invalid level9Code |
| 1022 | Invalid level10Code |
| 1023 | Invalid start date |
| 1024 | Invalid end date |
| 1025 | Start date must come before end date |
| 2001 | Failed to create list item |
| 2002 | Failed to update list item |
| 2003 | Failed to delete list item |
| 2004 | List item already exists in the database |
| 2005 | List item already exists as a deleted item in the database |
| 2006 | List item code error |
| 2007 | List item parent does not exist |
Changing a List Item Level Code
The list item level code (levelxcode element) is the unique identifier for the list item. For multiple level lists, the combination of the level codes is the unique identifier. This value cannot be updated by a standard update request, as this will result in a new duplicate list value instead.
To change a list item's level code, the original list item must be deleted (using the Post List Item Deletion request), then the new item with the updated code must be added (using the Post New List Item request).
NOTE: When you delete a list item, the system deactivates it, but keeps a copy in case the item has been used in any expense reports, invoices or requests. Existing reports, invoices or requests will still show the old list item. Any reports, invoices or requests created after the list item has been deleted will no longer show it in the list.
See also
List Item Web Service v1 - List Resource
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
Description
The configured lists in Concur. Can be single or multiple level lists.
Works With These Concur Products
- Expense for Concur Professional/Premium
- Expense for Concur Standard
- Invoice for Concur Professional/Premium
- Invoice for Concur Standard
- Travel Request for Concur Professional/Premium
Version
1.0
URI
https://www.concursolutions.com/api/expense/list/v1.0/
Headers
Content-Type header
application/xml
Accept header
application/xml
Operations
List Item Web Service v1 - Get a list of lists
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
This resource supports the following GET actions:
- Get List of Lists
- Get List Details
- Get List Items
Get Lists
Description
Retrieves the list of configured lists.
Get Lists Request
GET /api/expense/list/v1.0/ HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
Request parameters
None.
Headers
Authorization header
Authorization header with OAuth token for valid Concur user. The OAuth consumer must have one of the following user roles in Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. These roles allow the user to manage data for the entire company.
Accept header
application/xml
Get Lists Response
HTTP Responses
Root elements
This request will return a lists parent element containing a list child element for each configured list. The list element will contain the following child elements.
list child elements
| Element | Description |
|---|---|
| id | The list URI with encrypted ID. |
| items-link | The list item URI with encrypted ID. |
| batch-link | The batch URI associated with this list, with encrypted ID. |
| name | The name of the list as it appears in the user interface. |
| is-vendor | Whether this is a vendor list. Format: true/false |
| levels | The number of levels the list contains. |
XML Example of Successful Response
HTTPS/1.1 200 OK
Content-Type: application/xml
<lists xmlns="http://www.concursolutions.com/api/expense/list/2010/02">
<list>
<id>http://www.concursolutions.com/api/expense/list/v1.0/I8pq1l$rdSmdrEW23deOjPjyr4Wso0Wq$a</id>
<batch-link>http://www.concursolutions.com/api/expense/list/v1.0/I8pq1l$rdSmdrEW23deOjPjyr4Wso0Wq$a/batch</batch-link>
<name>Widget List</name>
<is-vendor>false</is-vendor>
<levels>1</levels>
<items-link>http://www.concursolutions.com/api/expense/list/v1.0/I8pq1l$rdSmdrEW23deOjPjyr4Wso0Wq$a/items/</items-link>
</list>
<list>
<id>http://www.concursolutions.com/api/expense/list/v1.0/jUwq11frTd$sweNd7s6s8O0fYi$piWwato</id>
<batch-link>http://www.concursolutions.com/api/expense/list/v1.0/jUwq11frTd$sweNd7s6s8O0fYi$piWwato/batch</batch-link>
<name>Organization List</name>
<is-vendor>false</is-vendor>
<levels>4</levels>
<items-link>http://www.concursolutions.com/api/expense/list/v1.0/jUwq11frTd$sweNd7s6s8O0fYi$piWwato/items/</items-link>
</list>
<list>
<id>http://www.concursolutions.com/api/expense/list/v1.0/4q2Hy86r45Klls$pseQEhNpz8Oxal7ytRe</id>
<batch-link>http://www.concursolutions.com/api/expense/list/v1.0/4q2Hy86r45Klls$pseQEhNpz8Oxal7ytRe/batch</batch-link>
<name>Airlines</name>
<is-vendor>true</is-vendor>
<levels>1</levels>
<items-link>http://www.concursolutions.com/api/expense/list/v1.0/4q2Hy86r45Klls$pseQEhNpz8Oxal7ytRe/items/</items-link>
</list>
</lists>
Get List Details
Description
Retrieves the list details for a specified list. Includes configuration information, not the list items.
Get List Details Request
GET /api/expense/list/v1.0/_{listID}_ HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
Request parameters
- {listID} Required. The identifier for the desired list. Example:
https://www.concursolutions.com/api/expense/list/v1.0/nqd1YesaKhCWCFIhY8JeBJYf2UGdpwJ2r - URI Source: This URI is returned in the id element by the Get List of Lists function.
Headers
Authorization header
Required. Authorization header with OAuth token for valid Concur user. The OAuth consumer must have one of the following user roles in Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. These roles allow the user to manage data for the entire company.
Accept header
application/xml
Get List Details Response
HTTP Responses
Content types
application/xml
Root elements
This request will return a list parent element. The list element will contain the following child elements.
list child elements
| Element | Description |
|---|---|
| batch-link | The batch URI associated with this list, with encrypted ID. |
| id | The list URI with encrypted ID. |
| is-vendor | Whether this is a vendor list. Format: true/false. |
| items-link | The list item URI with encrypted ID. |
| levels | The number of levels the list contains. |
| name | The name of the list as it appears in the user interface. |
XML Example of Successful Response
<list xmlns="http://www.concursolutions.com/api/expense/list/2010/02" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<batch-link>https://www.concursolutions.com/api/expense/list/v1.0/nqd1YesaKhCWCFIhY8JeBJYf2UGdpwJ2r/batch</batch-link>
<id>https://www.concursolutions.com/api/expense/list/v1.0/nqd1YesaKhCWCFIhY8JeBJYf2UGdpwJ2r</id>
<is-vendor>true</is-vendor>
<items-link>https://www.concursolutions.com/api/expense/list/v1.0/nqd1YesaKhCWCFIhY8JeBJYf2UGdpwJ2r/items</items-link>
<levels>1</levels>
<name>Travel Agents</name>
</list>
Get List Items
Description
Retrieves the list items for the specified list. A request sent without a specified parent list item code returns all level 1 list items. A request sent with a parent list item code returns all list items below that parent item. The result set can be filtered by passing in a filter string.
Get List Items Request
Request parameters
- {listID}/items Required. The identifier for the desired list, and the items keyword to indicate the request is for the list items. Example:
https://www.concursolutions.com/api/expense/list/v1.0/_{listID}_/items - {parentCode} Optional. The parent list item code. If this is included, the request will return all items below this list item. The parent code must be URL encoded.
- filter={filter} Optional. The result filter. The string value entered will be compared against the list item name and code fields, and only matching results will be returned. Example:
https://www.concursolutions.com/api/expense/list/v1.0/{_listID_}/items?parentCode={_parentcode_}&filter={_filter_}
Headers
Authorization header
Required. Authorization header with OAuth token for valid Concur user. The OAuth consumer must have one of the following user roles in Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard. These roles allow the user to manage data for the entire company.
Accept header
application/xml
XML Example Request
GET /api/expense/list/v1.0/jUwq11frTd$sweNd7s6s8O0fYi$piWwato/items/ HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
XML Example Request with Parent Code
GET /api/expense/list/v1.0/jUwq11frTd$sweNd7s6s8O0fYi$piWwato/items?parentCode=US HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
XML Example Request with Filter
GET /api/expense/list/v1.0/jUwq11frTd$sweNd7s6s8O0fYi$piWwato/items?filter=United HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
Get List Items Response
HTTP Responses
Response body root elements
This request will return a list-items parent element, with a list-item child element for each item returned. The list-item elements will contain the following child elements.
list-item child elements
| Element | Description |
|---|---|
| name | The list item name. |
| levelxcode | The item code for all specified levels, where x is replaced with the level number. If the request is for the children of a level 2 item, the level1code, level2code, and level3code elements will be returned. |
| items-link | The URI, including the parent code value, to request the list items beneath this list item. |
XML Example of Successful Response
<list-items xmlns="http://www.concursolutions.com/api/expense/list/2010/02">
<list-item>
<name>United States</name>
<level1code>US</level1code>
<items-link>https://www.concursolutions.com/api/expense/list/v1.0/jUwq11frTd$sweNd7s6s8O0fYi$piWwato/items/US/</items-link>
</list-item>
<list-item>
<name>United Kingdom</name>
<level1code>UK</level1code>
<items-link>https://www.concursolutions.com/api/expense/list/v1.0/jUwq11frTd$sweNd7s6s8O0fYi$piWwato/items/UK/</items-link>
</list-item>
<list-item>
<name>Canada</name>
<level1code>CA</level1code>
<items-link>https://www.concursolutions.com/api/expense/list/v1.0/jUwq11frTd$sweNd7s6s8O0fYi$piWwato/items/CA/</items-link>
</list-item>
<list-item>
<name>Mexico</name>
<level1code>MX</level1code>
<items-link>https://www.concursolutions.com/api/expense/list/v1.0/jUwq11frTd$sweNd7s6s8O0fYi$piWwato/items/MX/</items-link>
</list-item>
</list-items>
Receipts v3 (Deprecated)
This API has been deprecated.
Deprecation Date: 02/07/2017 Unsupported Date: 08/07/2017 Decommissioned Date: 01/31/2021 Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.Learn more in the API Lifecycle & Deprecation Policy.
Receipts v4 which replaces this API opens doors to global availability, enriched schemas, and better support for detailed tax content.
The Receipts resource represents receipts that can be posted to Concur by a provider company on behalf of opted-in users. This resource currently supports three types of receipts:
- General — A general-purpose receipt type that can be used for various goods or services
- Hotel — A receipt for a hospitality service, such as a hotel stay
- Ride — A receipt for a ride service
Notes:
- Receipts currently can't be Posted to users whose data is hosted in Concur's EU datacenter. Only users whose data is hosted in the US datacenter can receive e-receipts.
- The Receipt Service only accepts receipts that are up to 6 months old. Older receipts will not be accepted.
- Unlike all the other Concur API endpoints, the e-receipt requires the Concur Platform team to configure your sandbox to enable access.
Operations
Version
3.0
Create a new receipt
POST /api/v3.0/common/receipts
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
content |
- | body |
The receipt object to create |
Schema
Response
| Name | Type | Format | Description |
|---|---|---|---|
ID |
string |
- | |
URI |
string |
- |
Receipt
| Name | Type | Format | Description |
|---|---|---|---|
Amount |
Decimal |
- | Required The net amount of the transaction. A positive number means a payment is due. A negative number means a refund is due. Zero means no payment or refund is due. Range: -922,337,203,685,477 to 922,337,203,685,477 |
CurrencyCode |
string |
- | Required The 3-letter ISO 4217 currency code for the currency paid to the provider. |
CustomFields |
Array |
Custom Field | The parent element for custom fields. |
FormofPaymentCode |
string |
- | Required The code for the form of payment. Possible values: CASH (Cash), CCARD (Credit Card), CPAID (Company Paid) |
GeneralDetail |
GeneralDetail |
- | The details of a general transaction. This element is required when the Type value is General. |
HotelDetail |
HotelDetail |
- | The details of a hospitality service. This element is required when the Type value is Hotel. |
ImageBase64 |
string |
- | The binary receipt image in Base64 encoding. This API supports PNG, JPEG, JPG, and PDF file formats. |
MatchingFact |
MatchingFact |
- | Required The parent element for information that is used to match the receipt to the Concur user who initiated the transaction. The MatchingFact object must contain either a valid access token or a Concur login ID. |
Merchant |
Merchant |
- | Required The parent element for information about the provider who is posting the receipt. |
PaymentCard |
PaymentCard |
- | The parent element for the credit card used for payment. This element is required when the FormofPaymentCode value is CCARD. |
RideDetail |
RideDetail |
- | The details of a hired ride. This element is required when the Type value is Ride. |
TransactionDateTime |
DateTime |
- | Required The date and time when the transaction happened (in Local Time). Format: YYYY-MM-DDThh:mm |
Type |
string |
- | Required The type of receipt. Possible values: General, Ride, Hotel |
Custom Field
| Name | Type | Format | Description |
|---|---|---|---|
Name |
string |
- | Required The name of the custom field. Maximum length: 128 characters |
Value |
string |
- | Required The value of the custom field. Maximum length: 256 characters |
General Detail
| Name | Type | Format | Description |
|---|---|---|---|
LineItems |
Array |
Line Item | The parent element for the line items in the receipt. There is a LineItem child element for each line item. |
Line Item
| Name | Type | Format | Description |
|---|---|---|---|
Amount |
Decimal |
- | Required The total charged amount for the line item. Range: -922,337,203,685,477 to 922,337,203,685,477 |
Date |
DateTime |
- | The date and time when the line item was charged (in Local Time). Format: YYYY-MM-DDThh:mm |
Description |
string |
- | Required The item's description. Maximum length: 100 characters |
Description2 |
string |
- | Additional details about the item. In the receipt image, the secondary description appears on the line following the primary description. Maximum length: 32 characters |
Quantity |
Int32 |
- | The quantity of units. Format: Any positive number |
Rate |
Decimal |
- | The amount charged per unit. Range: -922,337,203,685,477 to 922,337,203,685,477 |
RateType |
string |
- | The unit of measure or rate type. Possible values: HOUR or PER HOUR, DAY or PER DAY, WEEK or PER WEEK, MONTH or PER MONTH. Maximum length: 10 characters |
Reference |
string |
- | The item's SKU, identifier, or some other attribute the provider uses to reference the item. Maximum length: 32 characters |
SequenceNumber |
Int32 |
- | Required The order in which the item appears in the sequence of line items. |
Hotel Detail
| Name | Type | Format | Description |
|---|---|---|---|
AverageDailyRoomRate |
Decimal |
- | Required The sum of the room rate for each night stayed, divided by the number of nights stayed. Range: -922,337,203,685,477 to 922,337,203,685,477 |
CheckinDateTime |
DateTime |
- | Required The check-in date and time (in Local Time). Format: YYYY-MM-DDThh:mm |
CheckoutDateTime |
DateTime |
- | Required The check-out date and time (in Local Time). Format: YYYY-MM-DDThh:mm |
ConfirmationNumber |
string |
- | The confirmation number for the booking. Maximum length: 32 characters |
GNR |
string |
- | The Guest Name Record (GNR) for the stay. Maximum length: 20 characters |
LineItems |
Array |
Line Item | The parent element for the line items in the receipt. There is a LineItem child element for each line item. |
NumberInParty |
Int32 |
- | The number of people for this stay. |
RatePlanType |
string |
- | The rate plan type that is used to calculate the room rate. Possible values are rate plan types defined using hospitality industry standards. Maximum length: 50 characters |
RoomNumber |
string |
- | The room number for the stay. Maximum length: 15 characters |
RoomType |
string |
- | The type of room. Possible values are room types defined using hospitality industry standards, such as Single, Double, Suite, and so on. Maximum length: 50 characters |
Matching Fact
| Name | Type | Format | Description |
|---|---|---|---|
Type |
string |
- | Required The type of matching fact that is used to identify the Concur user who owns the receipt. Possible values: OAuth, Login |
Value |
string |
- | Required The value of the matching fact. If the Type element is set to OAuth, this value must be the access token for the Concur user who owns the receipt. In this case, the access token must not be expired or revoked. If the Type element is set to Login, this value must be the login ID of the Concur user who owns the receipt. |
Merchant
| Name | Type | Format | Description |
|---|---|---|---|
Location |
Location |
- | Required The parent element for the provider location. |
Name |
string |
- | Required The name of the provider (Merchant). Maximum length: 64 characters |
Location
| Name | Type | Format | Description |
|---|---|---|---|
Address |
string |
- | The provider's street address. Maximum length: 100 characters |
Address2 |
string |
- | The provider's secondary street address. Maximum length: 50 characters |
City |
string |
- | The provider's city. Maximum length: 100 characters |
CountryCode |
string |
- | Required The provider's country. Format: 2-letter ISO 3166-1 country code |
CountrySubdivisionCode |
string |
- | The provider's state, province, or other country subdivision. Format: ISO 3166-2:2007 country subdivision code YYY, where YYY is the one-to-threeÐcharacter subdivision code |
EmailAddress |
string |
- | The provider's email address. Maximum length: 255 characters |
FaxNumber |
string |
- | The provider's fax number. Maximum length: 32 characters |
InternetAddress |
string |
- | The provider's Web address. Maximum length: 255 characters |
Name |
string |
- | The name of the provider's location, such as an airport, car rental agency, property, store, or other named location. Maximum length: 100 characters |
PostalCode |
string |
- | The provider's postal code. Maximum length: 20 characters |
TelephoneNumber |
string |
- | The provider's telephone number. Maximum length: 100 characters |
Payment Card
| Name | Type | Format | Description |
|---|---|---|---|
AuthorizationCode |
string |
- | The authorization code that the card interchange provided when it approved this purchase. Maximum length: 15 characters |
MaskedNumber |
string |
- | Required The masked card number for the credit card. With the exception of the AX (American Express) card type, this is the last four digits of the card number. For American Express, the value can be one of these, in order of preference: a) The first six digits and the last four digits of the card number. b) The last five digits. c) The last four digits. |
type |
string |
- | Required The card interchange for the credit card. Possible values: AX (American Express), DC (Diner's Club), DS (Discover), CA (MasterCard), VI (Visa), CB (Carte Blanche), ER (Enroute), TP (Universal Air Travel), JC (JCB), EC (EuroCard), OTHER (other types) |
Ride Detail
| Name | Type | Format | Description |
|---|---|---|---|
DriverName |
string |
- | The name of the driver. Maximum length: 255 characters |
DropoffLatitude |
Decimal |
- | The latitude of the ride end location. Range: -90 to 90 |
DropoffLongitude |
Decimal |
- | The longitude of the ride end location. Range: -180 to 180 |
EndDateTime |
DateTime |
- | Required The ending date and time for the ride (in Local Time). Format: YYYY-MM-DDThh:mm |
LineItems |
Array |
Line Item | The parent element for the line items in the receipt. There is a LineItem child element for each line item. |
StartDateTime |
DateTime |
- | Required The starting date and time for the ride (in Local Time). Format: YYYY-MM-DDThh:mm |
VehicleNumber |
string |
- | The unique identifier for the vehicle. Maximum length: 50 characters |
Request URL
https://www.concursolutions.com/api/v3.0/common/receipts
JSON example of a successful response
{
"ID": "270583561310",
"URI": ""
}
Request v3
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
Concur Request automates the spend request and approval process for both travel and everyday expenses, giving you the data you need to accurately track and better control spending. By increasing visibility into planned expenses and up-to-date budget data, you can make strategic spending decisions before any spending actually occurs. The Request resource provides many abilities, including viewing requests and transition of requests into the workflow.
Versions
Retrieve all requests
GET /api/v3.0/travelrequest/requests
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
offset |
string |
query |
Starting page offset |
limit |
Int32 |
query |
Number of records to return (default 100) |
user |
string |
query |
The login ID of the user who owns this Request. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter. |
status |
string |
query |
The Status search term specifies which travel request or approval status to return. If no Status value is sent, the default Status of Active will be used. |
modifiedAfter |
DateTime |
query |
This returns travel requests in which the associated dependents (header, entries, segments, allocations, attendees, comments) were modified after the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time (if desired) should be in UTC. The format is: YYYY-MM-DDThh:mm:ss. |
modifiedBefore |
DateTime |
query |
This returns travel requests in which the associated dependents (header, entries, segments, allocations, attendees, comments) were modified before the specified date and time. This search term can be used along with other search terms to narrow the results. The date and time (if desired) should be in UTC. The format is: YYYY-MM-DDThh:mm:ss. |
withSegmentTypes |
Boolean |
query |
Pass true to populate the SegmentType field in the result. |
Retrieve a request by ID
GET /api/v3.0/travelrequest/requests/{id}
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
Required The Request ID |
user |
string |
query |
The login ID of the user. Optional. The user must have the Web Services Admin (Professional) or Can Administer (Standard) user role to use this parameter. |
Submit a request by ID
POST /api/v3.0/travelrequest/requests/{id}/submit
Parameters
| Name | Type | Format | Description |
|---|---|---|---|
id |
string |
path |
The Request ID |
Schema
Request
| Name | Type | Format | Description |
|---|---|---|---|
AgencyOfficeName |
string |
- | The travel agency office name. |
AllocationFormID |
string |
- | The unique identifier of the Segment Form resource (See the "Forms" resource for more information). |
ApprovalLimitDate |
DateTime |
- | The date by which the Request must be approved. This element appears only when integrated with Concur Travel. |
ApprovalStatusCode |
string |
- | The code for the approval status the Request. |
ApprovalStatusName |
string |
- | The approval status of the Request. |
AuthorizedDate |
DateTime |
- | The date the Request was authorized. Format: YYYY-MM-DDThh:mm:ss. |
CashAdvances |
Array |
Cash Advance | This parent element has a CashAdvance child element for each cash advance. See the CashAdvance model for the full list of child elements. |
Comments |
Array |
Comment | This parent element has a Comment child element for each comment. See the Comment model for the full list of child elements. |
CreationDate |
DateTime |
- | The date of the Request was created. |
CurrencyCode |
string |
- | The 3-letter ISO 4217 currency code for the Request currency. The Request currency is defined as the Request creator's default reimbursement currency. |
CurrencyName |
string |
- | The currency name for the Request currency. The Request currency is defined as the Request creator's default reimbursement currency. |
Custom1 through Custom20 |
CustomField |
- | The details from the Custom fields. These fields may not have data, depending on the configuration. |
EmployeeName |
string |
- | The first, middle (or middle initial), and last name of the employee who created the Request. |
EndDate |
string |
- | The end date of the Request. |
EndTime |
string |
- | The end time for the Request. |
Entries |
Array |
Entry | This parent element has a RequestEntry child element for each entry. See the RequestEntry model for the full list of child elements. |
EverSentBack |
string |
- | Indicates whether the Request has ever been sent back to the employee. Format: Y/N |
Exceptions |
Array |
Exception | This parent element has an Exception child element for each exception. See the Exception model for the full list of child elements. |
ExtensionOf |
string |
- | The ID of the initial Request that this Request is an extension of or adendum to. |
HasException |
string |
- | Indicates whether the Request has exceptions. Format: Y/N |
HeaderFormID |
string |
- | The unique identifier of the Header Form resource (See the "Forms" resource for more information). |
LastModifiedDate |
DateTime |
- | The date the Request was last modified. Format: YYYY-MM-DDThh:mm:ss |
LoginID |
string |
- | The Concur login ID of the Request owner. |
Name |
string |
- | The name of the Request. |
PolicyID |
string |
- | The unique identifier of the policy that applies to this Request. Maximum length 64 characters. |
PolicyName |
string |
- | The name of the policy that applies to this Request. |
Purpose |
string |
- | The purpose of the Request. |
RequestID |
string |
- | The unique key for the Request. |
StartDate |
string |
- | The start date of the Request. |
StartTime |
string |
- | The start time for the Request. |
SubmitDate |
DateTime |
- | The date the Request was submitted. Format: YYYY-MM-DDThh:mm:ss. |
TotalApprovedAmount |
string |
- | The total amount of approved expenses in the Request. |
TotalPostedAmount |
string |
- | The total amount of the Request. |
TotalRemainingAmount |
string |
- | The total amount of expenses remaining in the Request. |
UserPermissions |
UserPermissions |
- | The actions that the user is allowed to perform on the Request. |
Cash Advance
| Name | Type | Format | Description |
|---|---|---|---|
AmountRequested |
string |
- | The amount requested in the cash advance, in the currency specified in the CurrencyCode element. |
ApprovalStatusName |
string |
- | The approval status of the cash advance. |
Comments |
Array |
Comment | This parent element has a Comment child element for each comment. Refer to the Comments model for the full list of child elements. |
CurrencyCode |
string |
- | The 3-letter ISO 4217 currency code for the cash advance currency. |
CurrencyName |
string |
- | The name of the currency for the cash advance. |
EmployeeCurrencyCode |
string |
- | The 3-letter ISO 4217 currency code for the employee's currency, also known as the home currency. |
EmployeeCurrencyName |
string |
- | The name of the employee's currency, also known as the home currency. |
ExchangeRate |
string |
- | The exchange rate that applies to the cash advance. |
IssueDate |
DateTime |
- | The issue date for the cash advance. |
RequestDate |
DateTime |
- | The date of cash advance request, obtained from the detailed cash advance record. |
StartingBalance |
string |
- | The initial balance for the cash advance. |
Comment
| Name | Type | Format | Description |
|---|---|---|---|
AuthorFirstName |
string |
- | The first name of the person who made the comment. |
AuthorLastName |
string |
- | The last name of the person who made the comment. |
CommentDateTime |
DateTime |
- | The time, in GMT, when the user made the comment. |
IsLatest |
bool |
- | Indicates that the comment is the last one. |
Value |
string |
- | The text of the Request header comment. |
Custom
| Name | Type | Format | Description |
|---|---|---|---|
Code |
string |
- | For list fields, this is the list item code. |
ListItemID |
string |
- | For list fields, this is the list item ID. |
Type |
string |
- | The custom field type. Possible values: Amount, Boolean, ConnectedList, Date, Integer, List, Number, Text |
Value |
string |
- | The value in the Org Unit or Custom field. For list fields, this is the name of the list item. Maximum length: 48 characters |
Entry
| Name | Type | Format | Description |
|---|---|---|---|
Allocations |
Array |
Allocation | This parent element has an Allocation child element for each associated allocation. See the Allocation model for the full list of child elements. |
ApprovedAmount |
string |
- | The approved amount of the Request entry in the Request currency. |
Comments |
Array |
Comment | This parent element has a Comment child element for each comment. See the Comments model for the full list of child elements. |
Custom1 through Custom40 |
CustomField |
- | The details from the Custom fields. These fields may not have data, depending on the configuration. |
EntryDescription |
string |
- | The description of the Request entry. |
EntryFormID |
string |
- | The unique identifier of the Entry Form resource (See the "Forms" resource for more information). |
Exceptions |
Array |
Exception | This parent element has an Exception child element for each exception. See the Exception model for the full list of child elements. |
ExchangeRate |
string |
- | The exchange rate that applies to the entry. |
ExpenseTypeName |
string |
- | The expense type name. |
ForeignAmount |
string |
- | The foreign amount of the Request entry. |
ForeignCurrencyCode |
string |
- | The 3-letter ISO 4217 currency code for the foreign currency amount of the Request entry. |
ForeignCurrencyName |
string |
- | The name of the currency for the foreign amount. |
LastModifiedDate |
DateTime |
- | The date the entry was last modified. Format: YYYY-MM-DDThh:mm:ss |
OrgUnit1 through OrgUnit6 |
CustomField |
- | The details from the Org Unit custom fields. These fields may not have data, depending on the configuration. |
PostedAmount |
string |
- | The posted amount of the Request entry in the Request currency. |
RemainingAmount |
string |
- | The remaining amount of the Request entry in the Request currency. |
Segments |
Array |
Segment | This parent element has a Segment child element for each segment associated with the travel request. See the Segment model for the full list of child elements. |
TransactionDate |
DateTime |
- | The date of the Request entry. |
TripType |
string |
- | ['ONE_WAY' or 'ROUND_TRIP' or 'MULTI_STOP'] Trip type of the air or rail segment. Possible values are: ONE_WAY, ROUND_TRIP and MULTI_STOP. |
Allocation
| Name | Type | Format | Description |
|---|---|---|---|
Custom1 through Custom20 |
CustomField |
- | The details from the Custom fields. These fields may not have data, depending on the configuration. |
Percentage |
string |
- | The percentage of the expense that is included in this allocation. |
Exception
| Name | Type | Format | Description |
|---|---|---|---|
Code |
string |
- | The system exception code defined for the exception. Example: BADCODE |
Level |
int |
- | The numeric level associated with the exception. Example: 99 |
Message |
string |
- | The user-facing message defined for the exception. |
Segment
| Name | Type | Format | Description |
|---|---|---|---|
ApprovedAmount |
string |
- | The approved amount of the segment in the Request currency. |
ArrivalDate |
string |
- | The arrival date of the segment. |
ArrivalTime |
string |
- | The arrival time of the segment. |
ClassOfServiceCode |
string |
- | The Class of Service Code from Concur Travel. Appears only when the Request is integrated with Concur Travel. |
Comments |
Array |
Comment | The list of comments added for this segment. |
Custom1 through Custom40 |
CustomField |
- | The details from the Custom fields. These fields may not have data, depending on the configuration. |
DepartureDate |
string |
- | The departure date of the segment. |
DepartureTime |
string |
- | The departure time of the segment. |
Exceptions |
Array |
Exception | This parent element has an Exception child element for each exception. Refer to the Exception model for the full list of child elements. |
ExchangeRate |
string |
- | The exchange rate that applies to the segment. |
FlightNumber |
string |
- | The flight number for air segments. Appears only when Request is integrated with Concur Travel. |
ForeignAmount |
string |
- | The foreign currency amount of the segment. |
ForeignCurrencyCode |
string |
- | The 3-letter ISO 4217 currency code for the foreign currency amount of the segment. |
ForeignCurrencyName |
string |
- | The name of the currency for the foreign amount of the segment. |
FormTypeCode |
string |
- | The code for form type of the segment type. |
FromLocationDetail |
string |
- | The code for the starting location. |
FromLocationID |
string |
- | The unique identifier of the departure location. (See the "Locations" resource for more information). |
FromLocationName |
string |
- | The name of the starting location. |
IsAgencyBooked |
string |
- | Indicates whether the air segment was agency booked. Format: Y/N. |
IsSelfBooked |
string |
- | Indicates whether the air segment was self booked. Format: Y/N. |
LastModifiedDate |
DateTime |
- | The date the segment was last modified. Format: YYYY-MM-DDThh:mm:ss |
OutboundSegmentID |
string |
- | REQ_SEGMENT_OUTBOUND_ID |
PostedAmount |
string |
- | The posted amount of the segment in the Request currency. |
RecordLocator |
string |
- | Appears only when the Request is integrated with Concur Travel. |
RemainingAmount |
string |
- | The remaining amount of the segment in the Request currency. |
SegmentFormID |
string |
- | The unique identifier of the Segment Form resource (See the "Forms" resource for more information). |
SegmentLocator |
string |
- | The unique identifier for the Concur Travel segment associated with this segment. Appears only when the Request is integrated with Concur Travel. |
SegmentType |
string |
- | The type of itinerary segment. Format: air, car, hotel, rail, dining, event, ground, taxi, parking, other and so on |
SegmentTypeCode |
string |
- | The code for the type of itinerary segment. |
ToLocationDetail |
string |
- | The code for the ending location. |
ToLocationID |
string |
- | The unique identifier of the arrival location. (See the "Locations" resource for more information). |
ToLocationName |
string |
- | The name of the ending location. |
TripLocator |
string |
- | The unique identifier for the Concur Travel trip associated with this segment. Appears only when the Request is integrated with Concur Travel. |
User Permissions
| Name | Type | Format | Description |
|---|---|---|---|
Links |
Array |
Link | The actions that the user is allowed to perform on the Request. |
Link
| Name | Type | Format | Description |
|---|---|---|---|
Action |
string |
- | The action that the user is allowed to perform on the resource. |
Method |
string |
- | The method of the request. Possible values: GET, POST, PUT and DELETE. |
Url |
string |
- | The URL of the resource that the user can access. |
Travel Profile v1 - User Notification
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
A subscription to a notification when the SAP Concur user changes the specified features of their SAP Concur account or data. Currently supports notifications for the following events: Itinerary change (create or update), Travel Profile basic information change, or Travel Profile Form of Payment change. This functionality is restricted to Travel Suppliers or TMCs (Travel Management Companies) who have registered with SAP Concur.
NOTE: This resource can only be accessed by partner applications that have selected the User API scope.
Resource URI
To subscribe:
https://www.concursolutions.com/api/user/v1.0/subscribe
To unsubscribe:
https://www.concursolutions.com/api/user/v1.0/unsubscribe
Headers
Content-Type Header
application/xml
Accept Header
application/xml
Operations
- Subscribe to notifications for itinerary changes
- Subscribe to notifications for payment changes
- Subscribe to notifications for travel profile changes
Subscribe to Notifications for Itinerary Changes
Subscribes or unsubscribes the travel supplier from notifications when the user adds, modifies, or cancels an itinerary. This functionality is only available to travel suppliers that have an application on the App Center tab of SAP Concur. The supplier must also have received authorization by the user to access their trip information.
Request
To subscribe:
shells://www.concursolutions.com/api/travelprofile/v1.0/subscribe?type=itinerary
To unsubscribe:
https://www.concursolutions.com/api/travelprofile/v1.0/unsubscribe?type=itinerary
Request Parameters
| Name | Description |
|---|---|
| type=itinerary | The type of subscription. Required. |
Headers
Authorization Header
Required. Authorization header with OAuth token for the desired SAP Concur user. This token is granted as part of the OAuth 2.0 Web flow authorization process.
Example: Subscribe to Itinerary Changes
POST https://www.concursolutions.com/api/travelprofile/v1.0/subscribe?type=itinerary HTTP/1.1
Authorization: OAuth {access token}
Post Notification Subscription for Itinerary Changes Response
Notification Format
The notification will be sent to the Postback URL that the supplier has registered with SAP Concur during application review. Suppliers can only have one postback URL for all notification types. The notification will include the type and oauth_token_key query parameters, specifying the OAuth information for the updated user:
https://postbackurl.com?type=Itinerary&oauth_token_key={oauth_token}
Response Body Schema
The request will include a Notification parent element, with the following child elements:
| Element | Description |
|---|---|
| ObjectType | ITINERARY |
| ObjectURI | The URI for the object. The developer can use the appropriate GET endpoint with the ObjectURI to get complete details for the trip. For Itinerary, the ObjectURI value is the same as the TripId value. |
| EventDateTime | When the event happened. Format: YYYY-MM-DDThh:mm:ss |
| EventType | The type of the change. Format: CREATE, UPDATE, CANCEL |
| Context | This is not used yet but will be used in the future to specify the change in the trip. Developers can use this in conjunction with EventType to decide how to process the notification. |
| TripId | The unique identifier for the trip. Format: String |
Example: Post a of Notification in XML Format
POST https://www.postbackurl.com?type=itinerary&oauth_token_key={oauthtoken} HTTP/1.1
Authorization: OAuth {access token}
Content-Type: application/xml
<?xml version="1.0" encoding="utf-8"?>
<Notification>
<ObjectType>ITINERARY</ObjectType>
<ObjectURI>https://www.concursolutions.com/api/travel/trip/v1.1/naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</ObjectURI>
<EventDateTime>2013-02-13T08:12:35</EventDateTime>
<EventType>CREATE</EventType>
<Context/>
<TripId>naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</TripId>
</Notification>
XML Example of Successful Response for Itinerary Changes
200 OK
Subscribe for Notifications for Payment Changes
Description
Subscribes or unsubscribes the travel supplier from notifications when the user's Form of Payment information changes. This functionality is only available to travel suppliers that have an application on the App Center tab of SAP Concur. The supplier must also have received authorization by the user to access their Form of Payment information.
NOTE: SAP Concur will send a notification when any area of the user's Form of Payment is updated. This may include fields that are not available through the Travel Profile web service.
Post Notification Subscription for Form of Payment Changes Request
Request Parameters
| Name | Description |
|---|---|
| type=fop | The type of subscription. Required. |
Examples
To subscribe:
https://www.concursolutions.com/api/travelprofile/v1.0/subscribe?type=fop
To unsubscribe:
https://www.concursolutions.com/api/travelprofile/v1.0/unsubscribe?type=fop
Headers
Authorization Header
Required. Authorization header with OAuth token for the desired SAP Concur user. This token is granted as part of the OAuth 2.0 Web flow authorization process.
XML Example Request
POST https://www.concursolutions.com/api/travelprofile/v1.0/subscribe?type=fop HTTP/1.1
Authorization: OAuth {access token}
Post Notification Subscription for Form of Payment Changes Response
Notification Format
The notification will be sent to the Postback URL that the supplier has registered with SAP Concur during application review. Suppliers can only have one postback URL for all notification types. The notification will include the type and oauth_token_key query parameters, specifying the OAuth information for the updated user:
https://postbackurl.com?type=FOP&oauth_token_key={oauth_token}
XML Example of Successful Response
200 OK
Subscribe for Notifications for Travel Profile Changes
Subscribes or unsubscribes the travel supplier from notifications when the user's Travel Profile information changes. This functionality is only available to travel suppliers that have an application on the App Center tab of SAP Concur. The supplier must also have received authorization by the user to access their travel profile information.
NOTE: SAP Concur will send a notification when any area of the user's Travel Profile is updated. This may include fields that are not available through the Travel Profile web service.
Request
Request parameters
| Name | Description |
|---|---|
| type=profile | The type of subscription. Required. |
Examples
To subscribe:
https://www.concursolutions.com/api/travelprofile/v1.0/subscribe?type=profile
To unsubscribe:
https://www.concursolutions.com/api/travelprofile/v1.0/unsubscribe?type=profile
Headers
Authorization header
Required. Authorization header with OAuth token for the desired SAP Concur user. This token is granted as part of the OAuth 2.0 Web flow authorization process.
Request
POST https://www.concursolutions.com/api/travelprofile/v1.0/subscribe?type=profile HTTP/1.1
Authorization: OAuth {access token}
Response
Notification Format
The notification will be sent to the Postback URL that the supplier has registered with SAP Concur during application review. Suppliers can only have one postback URL for all notification types. The notification will include the type and oauth_token_key query parameters, specifying the OAuth information for the updated user:
https://postbackurl.com?type=Profile&oauth_token_key={oauth_token}
XML Example of Successful Response
200 OK
Travel Profile v1 - Company Notification
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
A subscription to a notification when any user in the SAP Concur company changes the specified features of their SAP Concur account or data. Currently supports notifications for the following events: Itinerary change (create or update), Travel Profile basic information change.
This functionality requires that the partner complete the OAuth process with an administrative user from the SAP Concur company. This resource can only be accessed by partner applications that have selected the User API scope.
URI
To subscribe:
https://www.concursolutions.com/api/company/v1.0/subscribe
To unsubscribe:
https://www.concursolutions.com/api/company/v1.0/unsubscribe
Content Type
application/xml
Operations
- Post Company Notification Subscription for Itinerary Changes
- Post Company Notification Subscription for Payment Changes
- Post Company Notification Subscription for Travel Profile Changes
Post Company Notification Subscription for Itinerary Changes
Description
Subscribes or unsubscribes the partner from notifications when any users in the company add, modify, or cancel an itinerary. The partner must have received authorization using OAuth by an administrative user at the company to access the company's trip information.
Post Company Notification Subscription for Itinerary Changes Request
Headers
Request Parameters
| Name | Description |
|---|---|
type=itinerary |
Required. The type of subscription. |
Examples
To subscribe:
https://www.concursolutions.com/api/company/v1.0/subscribe?type=itinerary
To unsubscribe:
https://www.concursolutions.com/api/company/v1.0/unsubscribe?type=itinerary
Authorization Header
Required. Authorization header with OAuth token for an administrative user at the company. The user must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.
XML Example Request
POST http://www.concursolutions.com/api/company/v1.0/subscribe?type=itinerary HTTP/1.1
Authorization: OAuth {access token}
Post Company Notification Subscription for Itinerary Changes Response
Notification Format
The notification will be sent to the Postback URL that the partner has registered with SAP Concur during application review. Partners can only have one Postback URL for all notification types. The notification will include the type, oauth_token_key, userid_type, and userid_value query parameters, specifying the updated user:
https://postbackurl.com?type=itinerary&oauth_token_key={oauthtoken}&userid_type=login&userid_value=cm@example.com
Company Notification Subscription for Itinerary Changes Response Schema
The response body will include a Notification parent element, with the following child elements.
| Element | Description |
|---|---|
ObjectType |
ITINERARY |
ObjectURI |
The URI for the object. The developer can use the appropriate GET endpoint with the ObjectURI to get complete details for the trip. |
EventDateTime |
When the event happened. Format: YYYY-MM-DDThh:mm:ss |
EventType |
The type of the change. Format: CREATE, UPDATE, CANCEL |
Context |
This is not used yet but will be used in the future to specify the change in the trip. Developers can use this in conjunction with EventType to decide how to process the notification. |
TripId |
The unique identifier for the trip. Format: String |
XML Example of Successful Response
200 OK
XML Example of Notification
POST https://www.postbackurl.com?type=itinerary&oauth_token_key={oauthtoken}&userid_type=login&userid_value=cm@example.com HTTP/1.1
Content-Type: application/xml
<?xml version="1.0" encoding="utf-8"?>
<Notification>
<ObjectType>ITINERARY</ObjectType>
<ObjectURI>https://www.concursolutions.com/api/travel/trip/v1.1/naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</ObjectURI>
<EventDateTime>2013-02-13T08:12:35</EventDateTime>
<EventType>CREATE</EventType>
<Context/>
<TripId>naIzQJ0y2DBWjCIQOb2SHTsozwBsHDkdP</TripId>
</Notification>
Post Company Notification Subscription for Payment Changes
Description
Subscribes or unsubscribes the partner from notifications when the company's Payment information changes. The partner must have received authorization using OAuth by an administrative user at the company to access the company's form of payment information.
Post Company Notification Subscription for Payment Changes Request
Headers
Request Parameters
| Name | Description |
|---|---|
type=fop |
The type of subscription. Required. |
Examples
To subscribe:
https://www.concursolutions.com/api/company/v1.0/subscribe?type=fop
To unsubscribe:
https://www.concursolutions.com/api/company/v1.0/unsubscribe?type=fop
Headers
Authorization Header
Required. Authorization header with OAuth token for the desired SAP Concur user. This token is granted as part of the OAuth 2.0 Web flow authorization process.
XML Example Request
POST https://www.concursolutions.com/api/company/v1.0/subscribe?type=fop HTTP/1.1
Authorization: OAuth {access token}
Post Notification Subscription for Form of Payment Changes Response
Notification Format
The notification will be sent to the Postback URL that the supplier has registered with Concur during application review. Suppliers can only have one Postback URL for all notification types. The notification will include the type and oauth_token_key query parameters, specifying the OAuth information for the updated user:
https://postbackurl.com?type=FOP&oauth_token_key={oauth_token}
XML Example of Successful Response
200 OK
Post Company Notification Subscription for Travel Profile Changes
Description
Subscribes or unsubscribes the partner from notifications when the company's Travel Profile information changes. The partner must have received authorization using OAuth by an administrative user at the company to access the company's trip information.
NOTE: Concur will send a notification when any area of the user's Travel Profile is updated. This may include fields that are not available through the Travel Profile web service.
Post Company Notification Subscription for Travel Profile Changes Request
Headers
Request Parameters
| Name | Description |
|---|---|
type=profile |
Required. The type of subscription. |
Examples
To subscribe:
https://www.concursolutions.com/api/company/v1.0/subscribe?type=profile
To unsubscribe:
https://www.concursolutions.com/api/company/v1.0/unsubscribe?type=profile
Authorization Header
Required. Authorization header with OAuth token for an administrative user at the company. The user must have one of the following user roles in SAP Concur: Company Administrator or Web Services Administrator for Professional, or Can Administer for Standard.
XML Example Request
POST <https://www.concursolutions.com/api/company/v1.0/subscribe?type=profile> HTTP/1.1
Authorization: OAuth {access token}
Post Company Notification Subscription for Travel Profile Changes Response
Notification Format
The notification will be sent to the Postback URL that the partner has registered with SAP Concur during application review. Partners can only have one Postback URL for all notification types. The notification will include the type, oauth_token_key, userid_type, and userid_value query parameters, specifying the updated user:
https://postbackurl.com?type=profile&oauth_token_key={oauthtoken}&userid_type=login&userid_value=cm@example.com
The partner can use this information to make a Get Travel Profile request.
XML Example of Successful Response
200 OK
Profile v1 - User
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
Getting Started - Company API - User API
The Concur's user API is used to help provision and manage user accounts and profile details across multiple Concur products, including Expense, Invoice, Request, Travel and TripIt.
Version
1.0
Profile v1 User - Definition
The User schema is inspired by the work from System for Cross-domain Identity Management (SCIM), in particular:
- RFC 7643 System for Cross-domain Identity Management: Core Schema
- RFC 7644 System for Cross-domain Identity Management: Protocol (Optional)
The latest version of the User schema is always available at: user.json.
Get User
Profile supports user information retrieval with access tokens. And the access token will limit the user account, as well as the user attributes, that you can query for. You can use the following endpoint to lookup your user:
GET /profile/v1/me
(access token required)
Curl example:
curl -k -v -H "Authorization: Bearer $access-token" "https://$host/profile/v1/me"
The above calls will retrieve general user profile information. User resource also supports a schema parameter to limit or expand the data returned. To limit the amount of data returned, you can use ?schema=compact. To also retrieve expense related data, you can use ?schema=expense. You can also provide comma delimited schema list for the parameter, such as ?schema=compact,expense.
User details
Here is a sample user response, without compact, but with expense schema.
{
"active": true,
"id": "1c1e5ec5-1abc-4edd-a92a-bc551d0dfcd7",
"userType": "Enterprise",
"meta": {
"created": "2017-03-30T00:00:00.000",
"lastModified": "2017-07-03T17:46:00.000",
"principalType": "user",
"resourceType": "EnterpriseUser"
},
"preferredLanguage": "en",
"dateOfBirth": "1990-01-01",
"schemas": [
"com:concur:User:1.0",
"com:concur:Employee:1.0",
"com:concur:TravelPreferences:1.0",
"com:concur:Programs:1.0",
"com:concur:Documents:1.0",
"com:concur:Expense:0.2"
],
"gender": "Male",
"emails": [
{
"value": "1@profile-58dd7cd7.com",
"type": "Business",
"notifications": true,
"verified": false
},
{
"value": "test.user@concur.com",
"type": "Personal",
"notifications": true,
"verified": false
}
],
"com:concur:Documents:1.0": {
"passport": [
{
"number": "12345678",
"issuingCountry": "US",
"placeIssued": "Bellevue",
"dateIssued": "2017-06-02",
"expiration": "2023-06-30"
}
],
"visa": [
{
"number": "987654321",
"issuedByCountry": "AF",
"placeIssued": null,
"issuedForCountry": null,
"dateIssued": null,
"expiration": "2021-06-03"
}
]
},
"addresses": [
{
"type": "Home",
"streetAddress": "profile-58dd7cd7 home address",
"locality": "Redmond",
"region": "WA",
"postalCode": "98052",
"country": "US"
},
{
"type": "Work",
"streetAddress": "profile-58dd7cd7 office",
"locality": "bellevue",
"region": "WA",
"postalCode": "98004",
"country": "US"
}
],
"com:concur:Employee:1.0": {
"companyUUID": "d63d3d33-9255-41f4-8a1c-dabd6ab08578",
"companyInternalId": 277471,
"employeeId": "1@profile-58dd7cd7.com",
"jobTitle": "",
"managerId": "ae3204d3-a94f-47ad-94ef-8234ac40e560",
"orgUnitId": 80265
},
"com:concur:TravelPreferences:1.0": {
"air": {
"seat": {
"interrowPosition": "Aisle",
"sectionPosition": "Forward"
},
"homeAirport": "SEA",
"meal": "BLML"
},
"rail": {
"space": "DontCare",
"meal": "DontCare",
"bedCategory": "DontCare",
"fareSpaceComfort": "DontCare",
"deck": "DontCare",
"coach": "DontCare",
"bed": "DontCare",
"berth": "DontCare",
"noiseComfort": "DontCare",
"contingency": "DontCare",
"seat": "DontCare"
},
"car": {
"smoking": "NonSmoking",
"carType": "Mini",
"transmission": "Automatic",
"gpsEnabled": false,
"skirack": false
},
"hotel": {
"earlyCheckin": true,
"remark": null,
"pool": true,
"roomService": true,
"foamPillows": true,
"accessForBlind": true,
"accessForWheelchair": true,
"gym": true,
"roomType": "King",
"restaurant": true,
"rollawayBed": true,
"smoking": "NonSmoking",
"crib": true
}
},
"com:concur:Programs:1.0": {
"rail": [
{
"default": false,
"pointsNext": null,
"expiration": null,
"nextStatus": null,
"points": null,
"segments": null,
"parentChainVendorName": null,
"vendorName": "AccesRail",
"account": "123454321",
"statusBenefits": null,
"status": null,
"segmentsNext": null,
"parentChainVendorCode": null,
"vendorCode": "9B"
}
],
"air": [],
"hotel": [],
"car": []
},
"com:concur:Expense:0.2": {
"middleInitial": "T",
"middleName": "Test",
"loginId": "1@profile-58dd7cd7.com",
"ledger": "DEFAULT",
"countrySubdivision": null,
"driverId": null,
"cuuid": "8002699190004701412",
"cashAdvanceAccountCode": null,
"emailAddress": "1@profile-58dd7cd7.com",
"employeeId": "1@profile-58dd7cd7.com",
"firstName": "Concur",
"reimbursementType": "APCHECK",
"reimbursementCurrency": "USD",
"active": true,
"lastName": "User",
"uuId": "1c1e5ec5-1abc-4edd-a92a-bc551d0dfcd7",
"orgUnitData": [
{
"orgUnitName": "Expense Policy Group",
"orgUnitValue": null
}
],
"customData": [
{
"customFieldName": "Invoice Policy Group",
"customFieldValue": null
},
{
"customFieldName": "Employee Administration Country",
"customFieldValue": "United States"
}
],
"localeCode": "en_US",
"countryCode": "US"
}
}
HTTP Status Codes
| HTTP Status | Status | Description/Error Code |
|---|---|---|
| 200 | Success | Resource retrieved or updated |
| 201 | Success | Resource created |
| 204 | Success | Operation exectuted successfully, with no content returned |
| 301 | Moved Permanently | Resource is at a different location |
| 400 | Bad Request | - |
| 401 | Unauthorized | - |
| 403 | Forbidden | - |
| 404 | Resource not found | - |
| 429 | Rate limit reached | - |
| 500 | Internal Error | - |
| 503 | Service Unavailable | - |
Profile v1 - Getting Started
This API has been deprecated.
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
Getting Started - Company API - User API
The Concur's Profile API consists of a set of APIs to manage users, companies and apps within Concur. Profile API is the API for profile information for all Concur's profile data, including Enterprise applications such as Expense, Invoice, Request, and Travel, as well as Retail applications such as Hipmunk and TripIt.
Security
Profile API can be accessed using following authentication methods:
- Access Token based authentication
Access Token Authentication
An access token based authenticated call is made in the context of a principal (user/company/app). When an access token is used, it must be supplied in the 'Authorization' HTTP header by the caller.
The access token must have scopes that are relevant for the API call. For example, in order to call the Company API correctly, the token must include the company.read scope or the API call will fail. Similiarly, an API call to retrieve user information will succeed only if the token has user.read scope. You will receive "access denied" error if the scope does not match the API call you are trying to make.
To obtain or refresh an access token, please refer to OAuth2 - Getting Started.
Profile Endpoints
The base URL for the Profile API is:
https://host/profile/v1/
The following production hosts are available:
| Data Center | Environments | Host | Description |
|---|---|---|---|
| US | Production | https://us.api.concursolutions.com |
- |
| US | Production - access token | https://www-us.api.concursolutions.com |
This is for clients that cannot handle the server request for x.509 cert. |
| US | Implementation | https://us-impl.api.concursolutions.com |
- |
| EMEA | Production | https://emea.api.concursolutions.com |
- |
| EMEA | Production - access token | https://www-emea.api.concursolutions.com |
This is for clients that cannot handle the server request for x.509 cert. |
| EMEA | Implementation | https://emea-impl.api.concursolutions.com |
- |
| CHINA | Production | https://cn.api.concurcdc.cn |
- |
| CHINA | Production - access token | https://www-cn.api.concurcdc.cn |
This is for clients that cannot handle the server request for x.509 cert. |
Profile APIs are aware of the US and EMEA data centers. If an API call is made against a specific data center and the target resource is not stored in that data center, you will receive a "301-redirect" that points to the right location for the resource.
Caveats
Changes in Profile do not follow the typical notification or deprecation processes. If you want to be included in the Profile related notifications, please email profile@concur.com.
Travel Profile Resource v1
Deprecation Date: 04/01/2016
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.Learn more in the API Lifecycle & Deprecation Policy.
Current version: Travel Profile v2
Description
The Travel Profile resource represents a Concur travel profile which contains travel-relation information about a user, such as:
- Identity
- Contact information
- Rate preferences and discount codes
- Preferences by travel type
URI
https://{InstanceURL}/api/travelprofile/v1.0/profile
Operations
Get a travel profile
Gets the travel profile information for the specified user. The travel profile includes information such as the user's identity, contact information, rate preferences and discount codes, preferences by travel type, and custom fields. The travel profile information returned by this GET operation depends on whether the caller is a Travel Supplier, a TMC, or a mainstream developer:
- Travel Suppliers can get only the loyalty program information and discount codes for their own loyalty and discount programs.
- TMCs can get all loyalty programs and discount codes for the specified user.
- A mainstream developer cannot get any loyalty program or discount information.
Request parameters
All request paramenters are optional. To identify a specific user by login ID or XMLSyncID, you can specify the following request parameters:
| Parameter Name | Parameter Type | Data Type | Description |
|---|---|---|---|
| userid_type | Path | String | The type of user identification to use. Possible values are: login and xmlsyncid |
| userid_value | Path | String | The user's login ID or XMLSync ID, depending on which user type is selected. This parameter must be provided in conjunction with the userid_type parameter. |
Headers
Content-Type header
application/xml
Authorization header
Authorization: OAuth {access_token}
Where access_token is the OAuth 2.0 access token of the user whose travel profile information you want to retrieve. If you want to access company-wide travel profile information, the user account associated with the OAuth 2.0 access token must have a Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.
Data model
The data model of the response for the GET operation.
<ProfileResponse Status="Active|Inactive" Unique="{unique identifier for the user}">
<General>
<NamePrefix />
<FirstName />
<MiddleName />
<LastName />
<NameSuffix />
<PreferredName />
<JobTitle />
<PreferredLanguage />
<EReceiptOptIn />
<MarketingOptIn />
<HasOpenBooking />
<CountryCode />
<CompanyName />
</General>
<Telephones>
<Telephone Type="Cell|Other|Pager|Fax|Home|Work|Primary Mobile Phone">
<ContactOptIn />
<CountryCode />
<PhoneNumber />
<Extension />
</Telephone>
</Telephones>
<Addresses>
<Address Type="Home|Work|Billing|Other">
<AttentionLine />
<Line1 />
<Line2 />
<Line3 />
<MailStop />
<City />
<StateProvince />
<CountryCode />
<ZipCode />
<Laditude />
<Longitude />
</Address>
</Addresses>
<DriversLicenses>
<DriversLicense>
<DriversLicenseNumber />
<IssuingCountry />
<IssuingState />
<Expiration />
</DriversLicense>
</DriversLicenses>
<EmailAddresses>
<EmailAddress />
</EmailAddresses>
<RatePreferences>
<AAARate />
<AARPRate />
<GovtRate />
<MilitaryRate />
</RatePreferences>
<DiscountCodes>
<DiscountCode />
</DiscountCodes>
<Air>
<AirSmokingCode />
<AirMemberships>
<AirMembership>
<VendorCode />
<AccountNo />
<Status />
<StatusBenefits />
<PointTotal />
<SegmentTotal />
<NextStatus />
<PointsUntilNextStatus />
<SegmentsUntilNextStatus />
</AirMembership>
</AirMemberships>
<Seat>
<InterRowPositionCode />
<SectionPositionCode />
</Seat>
<Meals>
<MealCode />
</Meals>
<HomeAirport />
<AirOther />
<DHSRedressNumber />
<DHSKnownTravelerNumber />
</Air>
<Car>
<CarSmokingCode />
<CarGPS />
<CarOption />
<CarMemberships />
<CarMembership>
<VendorCode />
<AccountNo />
<Status />
<StatusBenefits />
<PointTotal />
<SegmentTotal />
<NextStatus />
<PointsUntilNextStatus />
<SegmentsUntilNextStatus />
</CarMembership>
<CarOther />
<CarSkiRack />
</Car>
<Hotel>
<SmokingCode />
<HotelMemberships />
<RoomType />
<HotelOther />
<preferFoamPillows />
<preferCrib />
<preferRollawayBed />
<preferGym />
<preferPool />
<preferRestaurant />
<preferWheelchairAccess />
<preferAccessForBlind />
<preferRoomService />
<preferEarlyCheckIn />
</Hotel>
<CustomFields>
<CustomField>
<Name />
<Value />
</CustomField>
</CustomFields>
</ProfileResponse>
ProfileResponse root element
The ProfileResponse root element contains the General, Telephones, Addresses, DriversLicenses, EmailAddresses, RatePreferences, DiscountCodes, Air, Car, Hotel, and CustomFields child elements. It has the attributes shown in the Data Model section.
General elements
The General parent element contains the following child elements:
| Element Name | Data Type | Description |
|---|---|---|
| NamePrefix | String | The user's name prefix. Format: Varchar(60) |
| FirstName | String | The user's first name. Format: Varchar(32) |
| MiddleName | String | The user's middle name. Format: Varchar(32) |
| LastName | String | The user's last name. Format: Varchar(32) |
| NameSuffix | String | The user's name suffix. Format: Varchar(60) |
| PreferredName | String | The user's preferred name. Format: Varchar(60) |
| JobTitle | String | The user's job title. Format: Nvarchar(255) |
| PreferredLanguage | String | The user's preferred language locale. Example: United States English is en-US. Format: Varchar(20) |
| EReceiptOptIn | String | Whether the user has opted in to receive e-receipts. Format: True/False |
| MarketingOptIn | String | Whether the user has opted in to receive marketing information. Format: True/False |
| HasOpenBooking | Boolean | Whether the user has the TripLink User (formerly Open Booking User) permission. Format: True/False |
| CountryCode | String | The country code in from the ISO 3166-1 alpha-2 country code specification. Format: Char(2) |
| CompanyName | String | The user's company name. |
Telephones elements
The Telephones parent element contains a Telephone child element for each included telephone. The Telephone element has the attributes shown in the Response Class section and contains the following child elements:
| Element Name | Data Type | Description |
|---|---|---|
| ContactOptIn | String | Whether the user has opted in to being contacted on this phone. Only appears when the phone type is Cell or Primary Mobile Phone. Format: True/False |
| CountryCode | String | The country code in from the ISO 3166-1 alpha-2 country code specification. Format: Char(2) |
| PhoneNumber | String | The phone number as entered by the user, which may contain characters such as () or -. Format: Char(60) NOTE: The user phone number may sometimes be incorrectly parsed if there are data input issues. |
| Extension | String | The phone extension. Format: Varchar(60) |
Addresses elements
The Addresses parent element contains an Address child element for each included address. The Address element has the attributes shown in the Response Class section and contains the following child elements:
NOTE: The values returned for the Address child elements are as entered by the user. The fields do not enforce formatting and may have a wide variety of values.
| Element Name | Data Type | Description |
|---|---|---|
| AttentionLine | String | Attention Line in the address. Format: Nvarchar(Unlimited) |
| Line1 | String | Address line 1. Format: Nvarchar(Unlimited) |
| Line2 | String | Address line 2. Format: Nvarchar(Unlimited) |
| Line3 | String | Address line 3. Format: Nvarchar(Unlimited) |
| MailStop | String | Address mail stop. Format: Nvarchar(Unlimited) |
| City | String | The city name. Format: Nvarchar(Unlimited) |
| StateProvince | String | The state or province. Format: Nvarchar(Unlimited) |
| CountryCode | String | The country code in from the ISO 3166-1 alpha-2 country code specification. Format: Char(2) |
| ZipCode | String | The zip code. Format: Varchar(20) |
| Longitude | String | Longitude value of Work Address. |
| Latitude | String | Latitude value of Work Address. |
DriversLicenses elements
The DriversLicenses parent element contains a DriversLicense child element for each each included licenses. The DriversLicense element contains the following child elements:
| Element Name | Data Type | Description |
|---|---|---|
| DriversLicenseNumber | String | The user's driver license identification number. Format: Varchar(30) |
| IssuingCountry | String | The country the license was issued in. Format: Char(2) |
| IssuingState | String | The state the license was issued in. Format: Varchar(2) |
| Expiration | String | The expiration date of the license. Format: YYYY-MM-DD |
EmailAddresses elements
The EmailAddresses parent element contains a EmailAddress child element for each included email address. It contains the following child element:
| Element Name | Data Type | Description |
|---|---|---|
| EmailAddress | String | The the user's email address. The EmailAddress element has two attributes: Type and Contact. The Type attribute specifies the type of email address and the possible values are: Business, Business2, Personal. The Contact attribute specifies whether the email address should be used for travel notifications and the possible values are True or False. Format: Varchar(255) |
RatePreferences elements
The RatePreferences parent element contains the following child element:
| Element Name | Data Type | Description |
|---|---|---|
| AAARate | Boolean | Whether the user is eligible for the AAA rate. Format: true/false |
| AARPRate | Boolean | Whether the user is eligible for the AARP rate. Format: true/false |
| GovtRate | Boolean | Whether the user is eligible for the Government rate. Format: true/false |
| MilitaryRate | Boolean | Whether the user is eligible for the Military rate. Format: true/false |
DiscountCodes elements
The DiscountCodes parent element contains a DiscountCode child element for each included discount code.
| Element Name | Data Type | Description |
|---|---|---|
| DiscountCode | String | The discount code for the specified vendor.The DiscountCode element has a Vendor attribute that specifies the name of the vendor for the discount code. |
Air elements
The Air parent element contains the user's air travel preferences and contains the following child elements:
| Element Name | Data Type | Description |
|---|---|---|
| AirSmokingCode | String | Whether the user wants a flight with smoking allowed. Legacy. Format: S, N, D. |
| AirMemberships | Membership | The AirMemberships element only appears if the request came from a travel supplier for this travel type, or from a TMC. This element contains an AirMembership child element for each included membership and includes the following child elements: |
| Seat | - | This parent element contains the user's Car travel preferences. The Car element contains the following child elements: |
| Meals | - | This parent element contains the MealCode child element that indicates the meal preference of the traveler. The possible values are: AVML = Vegetarian Hindu Meal BBML = Baby Meal BLML = Bland Meal CHML = Child Meal DBML = Diabetic Meal FPML = Fruit Platter GFML = Gluten Intolerant Meal HNML = Hindu Meal KSML = Kosher Meal LCML = Low Calorie Meal LFML = Low Fat Meal LSML = Low Salt Meal MOML = Muslim Meal NLML = Low Lactose Meal NSML = No Salt Meal PFML = Peanut Free Meal SFML = Seafood Meal SPML = Special Request Meal VGML = Vegetarian RVML = Vegetarian Raw Vegan Meal VLML = Vegetarian Lacto-Ovo VJML = Vegetarian Jain Meal VOML = Vegetarian Oriental Meal Note: Regular Meal will not return a value for this preference. |
| HomeAirport | String | The user's home airport |
| DHSRedressNumber | String | TSA Redress Number |
| DHSKnownTravelerNumber | String | TSA Known Traveler Number |
| AirOther | String | Other Air related description |
Air Memberships elements
| Element Name | Data Type | Description |
|---|---|---|
| VendorCode | String | The code for the vendor that manages the loyalty program. |
| AccountNo | String | The user's account identifier in the loyalty program. |
| Status | String | Name of the user's current level in the loyalty program. |
| StatusBenefits | String | Description of a benefit of the loyalty program at the current status. |
| PointTotal | String | The user's total number of points in the loyalty program. |
| SegmentTotal | String | The user's total segments in the loyalty program. |
| NextStatus | String | Name or description of next higher status level in the loyalty program. |
| PointsUntilNextStatus | String | Loyalty points required to next status level. |
| SegmentsUntilNextStatus | String | Booking segment to next status level. |
Seat elements
| Element Name | Data Type | Description |
|---|---|---|
| InterRowPositionCode | String | Preferred position in an airplane row. Format: Window, Aisle, Middle, Isolated, DontCare. |
| SectionPositionCode | String | Preference for position in plane. Format: F, B, R, D. |
Car elements
The Car parent element contains the user's car travel preferences. It contains the following child elements:
| Element Name | Data Type | Description |
|---|---|---|
| CarSmokingCode | String | Smoking car preferred. Format: S, N, O |
| CarGPS | String | Car GPS preference. Format: true/false. |
| CarOption | String | Car option preference. Format: Char(3) |
| CarMemberships | Membership | The CarMemberships element only appears if the request came from a travel supplier for this travel type, or from a TMC. This element contains a CarMembership child element for each included membership. The CarMembership element has the following child elements: |
| CarOther | String | Other Car related description. Format: Char(30) |
| CarSkiRack | String | Car ski rack preference. Format: true/false. |
Car Memberships elements
| Element Name | Data Type | Description |
|---|---|---|
| VendorCode | String | The code for the vendor that manages the loyalty program. |
| AccountNo | String | The user's account identifier in the loyalty program. |
| Status | String | Name of the user's current level in the loyalty program. |
| StatusBenefits | String | Description of a benefit of the loyalty program at the current status. |
| PointTotal | String | The user's total number of points in the loyalty program. |
| SegmentTotal | String | The user's total segments in the loyalty program. |
| NextStatus | String | Name or description of next higher status level in the loyalty program. |
| PointsUntilNextStatus | String | Loyalty points required to next status level. |
| SegmentsUntilNextStatus | String | Booking segment to next status level. |
Hotel elements
The Hotel parent element contains the user's hotel travel preferences. It contains the following child elements:
| Element Name | Data Type | Description |
|---|---|---|
| SmokingCode | String | Smoking room preference. Format: S, N,D |
| HotelMemberships | - | This parent element only appears if the request came from a travel supplier for this travel type, or from a TMC. This element contains a HotelMembership child element for each included membership. The HotelMembership element has the following child elements: |
| RoomType | String | Hotel room preference. Values are: H, 2, K, Q, 1, T |
| HotelOther | String | Other Hotel related description. Format: Varchar(30) |
| PreferFoamPillows | String | Whether the user prefers foam pillows. Format: true/false. |
| PreferCrib | String | Whether the user prefers to have a crib. Format:true/false. |
| PreferRollawayBed | String | Whether the user prefers to have a rollaway bed. Format:true/false. |
| PreferGym | String | Whether the user prefers a hotel with a gym. Format:true/false. |
| preferPool | String | Whether the user prefers a hotel with a pool. Format:true/false. |
| preferRestaraunt | String | Whether the user prefers a hotel with a restaurant. Format:true/false. |
| preferWheelchairAccess | String | Whether the user requires wheelchair access. Format: true/false. |
| preferAccessForBlind | String | Whether the user requires a room with access for blind guests. Format:true/false. |
| preferRoomService | String | Whether the user prefers a hotel with room service. Format:true/false. |
| preferEarlyCheckIn | String | Whether the user prefers a hotel with early check in. Format:true/false. |
Hotel Memberships elements
| Element Name | Data Type | Description |
|---|---|---|
| VendorCode | String | The code for the vendor that manages the loyalty program. |
| AccountNo | String | The user's account identifier in the loyalty program. |
| Status | String | Name of the user's current level in the loyalty program. |
| StatusBenefits | String | Description of a benefit of the loyalty program at the current status. |
| PointTotal | String | The user's total number of points in the loyalty program. |
| SegmentTotal | String | The user's total segments in the loyalty program. |
| NextStatus | String | Name or description of next higher status level in the loyalty program. |
| PointsUntilNextStatus | String | Loyalty points required to next status level. |
| SegmentsUntilNextStatus | String | Booking segment to next status level. |
CustomFields elements
The CustomFields parent element contains child elements that specify custom fields in a travel profile. It contains a CustomField child element for each custom field. To retrieve this information, the Travel Profile, Custom Fields scope must be selected in the Register Partner Application page under Web Services.
CustomField child elements
For each custom field, the CustomField element has a Name and Value child element.
| Element Name | Data Type | Description |
|---|---|---|
| Name | String | The name of the custom field. For example, Employee, Cost Centre, Fund, PassportNumber, Visa, and Assistants. |
| Value | String | The value of the custom field. If the value is null, the Value child element is omitted. |
Examples for Travel Suppliers
Example 1: Get the travel profile for the user associated with the specified OAuth 2.0 access token
Request
GET {InstanceURI}/api/travelprofile/v1.0/profile HTTP/1.1
Authorization: OAuth {access token}
Response
HTTP/1.1 200 OK
Content-Type: application/xml
<ProfileResponse Status="Active" Unique="CM12345678">
<General>
<NamePrefix />
<FirstName>Maria</FirstName>
<MiddleName>X</MiddleName>
<LastName>Black</LastName>
<NameSuffix />
<PreferredName />
<JobTitle>Finance Manager</JobTitle>
<PreferredLanguage>en-us</PreferredLanguage>
<EReceiptOptIn>True</EReceiptOptIn>
<MarketingOptIn>True</MarketingOptIn>
<HasOpenBooking>true</HasOpenBooking>
<CountryCode>US</CountryCode>
<CompanyName>ExampleDotCom</CompanyName>
</General>
<Telephones>
<Telephone Type="Work">
<CountryCode>001</CountryCode>
<PhoneNumber>5555551234</PhoneNumber>
<Extension />
</Telephone>
<Telephone Type="Cell">
<CountryCode>001</CountryCode>
<PhoneNumber>4155544321</PhoneNumber>
<Extension />
<ContactOptIn>True</ContactOptIn>
</Telephone>
</Telephones>
<Addresses>
<Address Type="Work">
<AttentionLine>Finance Department</AttentionLine>
<Line1>1234 Rainy Street.</Line1>
<Line2>Suite 442</Line2>
<Line3 />
<MailStop />
<City>Seattle</City>
<StateProvince>WA</StateProvince>
<CountryCode>US</CountryCode>
<ZipCode>98102</ZipCode>
<Longitude>-77.040706000000</Longitude>
<Latitude>38.812690000000</Latitude>
</Address>
<Address Type="Home">
<AttentionLine />
<Line1>1234 1st Ave. S</Line1>
<Line2>Apt. 821</Line2>
<Line3 />
<MailStop />
<City>Seattle</City>
<StateProvince>WA</StateProvince>
<CountryCode>US</CountryCode>
<ZipCode>98102</ZipCode>
<Longitude>-77.040706000000</Longitude>
<Latitude>38.812690000000</Latitude>
</Address>
</Addresses>
<DriversLicenses>
<DriversLicense>
<DriversLicenseNumber>MIL112233452</DriversLicenseNumber>
<IssuingCountry>US</IssuingCountry>
<IssuingState>WA</IssuingState>
<Expiration>2018-05-22</Expiration>
</DriversLicense>
</DriversLicenses>
<EmailAddresses>
<EmailAddress Type="Business" Contact="True">mariab@example.com</EmailAddress>
</EmailAddresses>
<RatePreferences>
<AAARate>true</AAARate>
<AARPRate>false</AARPRate>
<GovtRate>false</GovtRate>
<MilitaryRate>false</MilitaryRate>
</RatePreferences>
<DiscountCodes>
<DiscountCode Vendor="Marriott">1234567899</DiscountCode>
</DiscountCodes>
<Air>
<AirSmokingCode>S</AirSmokingCode>
<AirMemberships>
<AirMembership>
<VendorCode>AA</VendorCode>
<AccountNo>K12345</AccountNo>
<Status>Normal</Status>
<StatusBenefits>N/A</StatusBenefits>
<PointTotal>1234</PointTotal>
<SegmentTotal>2</SegmentTotal>
<NextStatus>Super</NextStatus>
<PointsUntilNextStatus>444</PointsUntilNextStatus>
<SegmentsUntilNextStatus>2</SegmentsUntilNextStatus>
</AirMembership>
</AirMemberships>
<Seat>
<InterRowPositionCode>Window</InterRowPositionCode>
<SectionPositionCode>F</SectionPositionCode>
</Seat>
<Meals>
<MealCode>VGML</MealCode>
</Meals>
<HomeAirport>SEA</HomeAirport>
<AirOther />
</Air>
<Car>
<CarSmokingCode>N</CarSmokingCode>
<CarGPS>True</CarGPS>
<CarOption />
<CarMemberships>
<CarMembership>
<VendorCode>ZE</VendorCode>
<AccountNo>ABCDEF</AccountNo>
<Status>Newbie</Status>
<StatusBenefits>10% discount</StatusBenefits>
<PointTotal>44</PointTotal>
<SegmentTotal>8</SegmentTotal>
<NextStatus>Veteran</NextStatus>
<PointsUntilNextStatus>55</PointsUntilNextStatus>
<SegmentsUntilNextStatus>12</SegmentsUntilNextStatus>
</CarMembership>
<CarMembership>
<VendorCode>XW</VendorCode>
<AccountNo>GHIJK</AccountNo>
<Status>Gold</Status>
<StatusBenefits>30% discount</StatusBenefits>
<PointTotal>1000</PointTotal>
<SegmentTotal>50</SegmentTotal>
<NextStatus>VIP</NextStatus>
<PointsUntilNextStatus>500</PointsUntilNextStatus>
<SegmentsUntilNextStatus>25</SegmentsUntilNextStatus>
</CarMembership>
</CarMemberships>
<CarOther />
<CarSkiRack>False</CarSkiRack>
</Car>
<Hotel>
<SmokingCode>N</SmokingCode>
<HotelMemberships />
<RoomType>K</RoomType>
<HotelOther />
<PreferFoamPillows>True</PreferFoamPillows>
<PreferCrib>False</PreferCrib>
<PreferRollawayBed>True</PreferRollawayBed>
<PreferGym>True</PreferGym>
<preferPool>True</preferPool>
<preferRestaraunt>True</preferRestaraunt>
<preferWheelchairAccess>False</preferWheelchairAccess>
<preferAccessForBlind>False</preferAccessForBlind>
<preferRoomService>True</preferRoomService>
<preferEarlyCheckIn>False</preferEarlyCheckIn>
</Hotel>
<CustomFields>
<CustomField>
<Name>Employee ID</Name>
<Value>12345</Value>
</CustomField>
<CustomField>
<Name>Cost Centre</Name>
<Value>Headquarters</Value>
</CustomField>
<CustomField>
<Name>Fund</Name>
<Value>StudentTraining</Value>
</CustomField>
<CustomField>
<Name>Passport Number></Name>
<Value>AUS1234</Value>
</CustomField>
<CustomField>
<Name>Visa</Name>
<Value>EUvisa1234</Value>
</CustomField>
<CustomField>
<Name>Assistants</Name>
<Value>John Smith</Value>
</CustomField>
</CustomFields>
</ProfileResponse>
Example 2: Get the travel profile for a user with a specific login ID
Request
GET https://www.concursolutions.com/api/travelprofile/v1.0/profile?userid_type=login&userid_value=cm@example.com HTTP/1.1
Authorization: OAuth {access token}
Response
The response is the same as in Example 1.
Examples for TMCs
Example 3: Get the travel profile for the user associated with the specified OAuth 2.0 access token
Request
GET {InstanceURI}/api/travelprofile/v1.0/profile HTTP/1.1
Authorization: OAuth {access token}
Response
HTTP/1.1 200 OK
Content-Type: application/xml
<ProfileResponse Status="Active" Unique="CM12345678">
<General>
<NamePrefix />
<FirstName>Maria</FirstName>
<MiddleName>X</MiddleName>
<LastName>Black</LastName>
<NameSuffix />
<PreferredName />
<JobTitle>Finance Manager</JobTitle>
<PreferredLanguage>en-us</PreferredLanguage>
<EReceiptOptIn>True</EReceiptOptIn>
<MarketingOptIn>True</MarketingOptIn>
<HasOpenBooking>true</HasOpenBooking>
<CountryCode>US</CountryCode>
<CompanyName>ExampleDotCom</CompanyName>
</General>
<Telephones>
<Telephone Type="Work">
<CountryCode>001</CountryCode>
<PhoneNumber>5555551234</PhoneNumber>
<Extension />
</Telephone>
<Telephone Type="Cell">
<CountryCode>001</CountryCode>
<PhoneNumber>4155544321</PhoneNumber>
<Extension />
<ContactOptIn>True</ContactOptIn>
</Telephone>
</Telephones>
<Addresses>
<Address Type="Work">
<AttentionLine>Finance Department</AttentionLine>
<Line1>1234 Rainy Street.</Line1>
<Line2>Suite 442</Line2>
<Line3 />
<MailStop />
<City>Seattle</City>
<StateProvince>WA</StateProvince>
<CountryCode>US</CountryCode>
<ZipCode>98102</ZipCode>
<Longitude>-77.040706000000</Longitude>
<Latitude>38.812690000000</Latitude>
</Address>
<Address Type="Home">
<AttentionLine />
<Line1>1234 1st Ave. S</Line1>
<Line2>Apt. 821</Line2>
<Line3 />
<MailStop />
<City>Seattle</City>
<StateProvince>WA</StateProvince>
<CountryCode>US</CountryCode>
<ZipCode>98102</ZipCode>
<Longitude>-77.040706000000</Longitude>
<Latitude>38.812690000000</Latitude>
</Address>
</Addresses>
<DriversLicenses>
<DriversLicense>
<DriversLicenseNumber>MIL112233452</DriversLicenseNumber>
<IssuingCountry>US</IssuingCountry>
<IssuingState>WA</IssuingState>
<Expiration>2018-05-22</Expiration>
</DriversLicense>
</DriversLicenses>
<EmailAddresses>
<EmailAddress Type="Business" Contact="True">mariab@example.com</EmailAddress>
</EmailAddresses>
<RatePreferences>
<AAARate>true</AAARate>
<AARPRate>false</AARPRate>
<GovtRate>false</GovtRate>
<MilitaryRate>false</MilitaryRate>
</RatePreferences>
<DiscountCodes>
<DiscountCode Vendor="Marriott">1234567899</DiscountCode>
<DiscountCode Vendor="IHG">111222333</Discount</span>
</DiscountCodes>
<Air>
<AirSmokingCode>S</AirSmokingCode>
<AirMemberships>
<AirMembership>
<VendorCode>AA</VendorCode>
<AccountNo>K12345</AccountNo>
<Status>Normal</Status>
<StatusBenefits>N/A</StatusBenefits>
<PointTotal>1234</PointTotal>
<SegmentTotal>2</SegmentTotal>
<NextStatus>Super</NextStatus>
<PointsUntilNextStatus>444</PointsUntilNextStatus>
<SegmentsUntilNextStatus>2</SegmentsUntilNextStatus>
</AirMembership>
</AirMemberships>
<Seat>
<InterRowPositionCode>Window</InterRowPositionCode>
<SectionPositionCode>NOPREF</SectionPositionCode>
</Seat>
<Meals>
<MealCode>VGML</MealCode>
</Meals>
<HomeAirport>SEA</HomeAirport>
<AirOther />
</Air>
<Car>
<CarSmokingCode>N</CarSmokingCode>
<CarGPS>True</CarGPS>
<CarOption />
<CarMemberships>
<CarMembership>
<VendorCode>ZE</VendorCode>
<AccountNo>ABCDEF</AccountNo>
<Status>Newbie</Status>
<StatusBenefits>10% discount</StatusBenefits>
<PointTotal>44</PointTotal>
<SegmentTotal>8</SegmentTotal>
<NextStatus>Veteran</NextStatus>
<PointsUntilNextStatus>55</PointsUntilNextStatus>
<SegmentsUntilNextStatus>12</SegmentsUntilNextStatus>
</CarMembership>
<CarMembership>
<VendorCode>XW</VendorCode>
<AccountNo>GHIJK</AccountNo>
<Status>Gold</Status>
<StatusBenefits>30% discount</StatusBenefits>
<PointTotal>1000</PointTotal>
<SegmentTotal>50</SegmentTotal>
<NextStatus>VIP</NextStatus>
<PointsUntilNextStatus>500</PointsUntilNextStatus>
<SegmentsUntilNextStatus>25</SegmentsUntilNextStatus>
</CarMembership>
</CarMemberships>
<CarOther />
<CarSkiRack>False</CarSkiRack>
</Car>
<Hotel>
<SmokingCode>N</SmokingCode>
<HotelMemberships />
<RoomType>K</RoomType>
<HotelOther />
<PreferFoamPillows>True</PreferFoamPillows>
<PreferCrib>False</PreferCrib>
<PreferRollawayBed>True</PreferRollawayBed>
<PreferGym>True</PreferGym>
<preferPool>True</preferPool>
<preferRestaraunt>True</preferRestaraunt>
<preferWheelchairAccess>False</preferWheelchairAccess>
<preferAccessForBlind>False</preferAccessForBlind>
<preferRoomService>True</preferRoomService>
<preferEarlyCheckIn>False</preferEarlyCheckIn>
</Hotel>
<CustomFields>
<CustomField>
<Name>Employee ID</Name>
<Value>12345</Value>
</CustomField>
<CustomField>
<Name>Cost Centre</Name>
<Value>Headquarters</Value>
</CustomField>
<CustomField>
<Name>Fund</Name>
<Value>StudentTraining</Value>
</CustomField>
<CustomField>
<Name>Passport Number></Name>
<Value>AUS1234</Value>
</CustomField>
<CustomField>
<Name>Visa</Name>
<Value>EUvisa1234</Value>
</CustomField>
<CustomField>
<Name>Assistants</Name>
<Value>John Smith</Value>
</CustomField>
</CustomFields>
</ProfileResponse>
Example 4: Get the travel profile for a user with a specific login ID
Request
GET https://www.concursolutions.com/api/travelprofile/v1.0/profile?userid_type=login&userid_value=cm@example.com HTTP/1.1
Authorization: OAuth {access token}
Response
The response is the same as in Example 3.
Get a list of travel profile summaries
Gets the list of travel profile summaries that have been updated since the specified date. The response is separated into pages.
Request
GET {InstanceURI}/api/travelprofile/v1.0/profile?LastModifiedDate=2015-01-01T01:00:00 HTTP/1.1
Authorization: OAuth {access token}
Request parameters
All request paramenters are optional. To identify a specific user by login ID or XMLSyncID, you can specify the following request parameters.
Parameter Name|Required/Optional|Parameter Type|Data Type|Description ---|---|---|--- LastModifiedDate|Required|path|string|The date and time, in UTC, that the profiles must be updated after to be included in the response. Format: YYYY-MM-DDThh:mm:ss Page|Optional|path|string|The number of pages to retrieve. If the page is outside the number of existing pages, the response elements will be empty ItemsPerPage|Optional|path|string|The number of travel profiles per page. The maximum value is 200. The default value is 200.
Headers
Accept header
application/xml
Authorization header
Authorization: OAuth {access_token}
Where access_token is the OAuth 2.0 access token of the user whose travel profile summaries you want to retrieve. If you want to access company-wide travel profile information, the user account associated with the OAuth 2.0 access token must have a Concur account with one of these roles: Web Services Administrator for Professional or Can Administer for Standard.
Data model
The data model of the response for the GET operation.
<ConnectResponse>
<Metadata>
<Paging>
<TotalPages />
<TotalItems />
<Page />
<ItemsPerPage />
<PreviousPageURL />
<NextPageURL />
</Paging>
</Metadata>
<Data>
<ProfileSummary>
<LoginID />
<XmlProfileSyncID />
<ProfileLastModifiedUTC />
</ProfileSummary>
</Data>
</ConnectResponse>
Response
ConnectResponse root element
The ConnectResponse root element contains the General, Telephones, Addresses, DriversLicenses, EmailAddresses, RatePreferences, DiscountCodes, Air, Car, Hotel, and CustomFields child elements. It has the attributes shown in the Response Class section.
Metadata element
The Metadata parent element contains the Paging child element.
Paging elements
The Paging parent element contains contains the paging information for the response and it contains the following child elements:
| Element Name | Data Type | Description |
|---|---|---|
| TotalPages | String | The total number of pages to return. |
| TotalItems | String | The total number of profiles the query returned. |
| Page | String | The page number for the set of results in the current response. |
| ItemsPerPage | String | The number of items set to display per page. |
| PreviousPageURL | String | The URI to the previous page of results. This element will be empty when there are no previous pages. |
| NextPageURL | String | The URI to the next set of results. This element will be empty when there are no next pages. |
Data element
The Data parent element contains a ProfileSummary child element for each included travel profile.
ProfileSummary
The Paging parent element contains contains the paging information for the response and it contains the following child elements:
| Element Name | Data Type | Description |
|---|---|---|
| LoginID | String | The Concur user login ID. |
| XMLProfileSyncID | String | TThe user's XML Profile Sync ID, if available. |
| ProfileLastModifiedUTC | String | The date, in UTC, when the travel profile was last modified. Format: YYYY-MM-DDThh:mm:ss. |
Example
This example gets the list of travel profile summaries modified after January 1 2015.
Request
GET {InstanceURI}/api/travelprofile/v1.0/profile?LastModifiedDate=2015-01-01T01:00:00 HTTP/1.1
Authorization: OAuth {access token}
Response
HTTP/1.1 200 OK
Content-Type: application/xml
<ConnectResponse>
<Metadata>
<Paging>
<TotalPages>1</TotalPages>
<TotalItems>2</TotalItems>
<Page>1</Page>
<ItemsPerPage>200</ItemsPerPage>
<PreviousPageURL />
<NextPageURL />
</Paging>
</Metadata>
<Data>
<ProfileSummary>
<LoginID>mariab@company1.com</LoginID>
<XmlProfileSyncID>string123</XmlProfileSyncID>
<ProfileLastModifiedUTC>2015-01-01T01:00:00</ProfileLastModifiedUTC>
</ProfileSummary>
<ProfileSummary>
<LoginID>peterk@company1.com</LoginID>
<XmlProfileSyncID>string456</XmlProfileSyncID>
<ProfileLastModifiedUTC>2015-01-01T01:00:00</ProfileLastModifiedUTC>
</ProfileSummary>
</Data>
</ConnectResponse>
Trip Approval v1
This API has been deprecated.
Retired Date: 10/08/2018
Partners and customers using a deprecated API should contact SAP Concur and discuss moving to the latest versions.
Learn more in the API Lifecycle & Deprecation Policy.
Description
The Trip Approval resource allows clients to approve or reject trips. Clients send the unique identifier for the trip, the approver email and the workflow action to be performed (either approve or reject).
Resource URI
https://www.concursolutions.com/api/tws/v1.0/TripApproval/DoApproval
Supported Content Types
- application/xml
Supported Accept Types
- application/xml
Operations
- Update trip approval status
Update trip approval status
Updates the specified trip as approved or rejected by the supplied approver. Can supply either the ItinLocator or the RecordLocator value.
Request
POST /api/tws/v1.0/TripApproval/DoApproval HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content type
application/xml
Authorization header
The Authorization header must have an OAuth token for a valid Concur trip approver.
Request body elements
The request will contain a TripApprovalRQ parent element with a TransactionId attribute. The TransactionId value is used to identify request and response pairs, and can contain any alphanumeric string that does not contain special characters. The TripApprovalRQ element contains the following child elements:
| Element | Required? | Description |
|---|---|---|
| Version | Y | The version of the web service. Currently 1.0. |
| ItinLocator | N | The Itinerary Services Record Locator (also known as Itin Locator or Trip Locator). NOT the GDS record locator. If value of ItinLocator is unknown, RecordLocator element should be passed instead. |
| RecordLocator | Y, if the ItinLocator is not sent | The GDS record locator. Should be passed only if the ItinLocator is unknown. |
| ApproverLogin | Y | The Travel approver's login ID. |
| Action | Y | The workflow action to take. Supported values are approve, reject. |
Response
Response body elements
This request will return a TripApprovalRS parent element with a matching TransactionId attribute. The TripApprovalRS element will contain the following child elements:
| Element | Required? | Description |
|---|---|---|
| Version | Y | The version of the web service. Currently 1.0. |
| ItinLocator | N | The Itinerary Services Record Locator (also known as Itin Locator or Trip Locator). NOT the GDS record locator. If value of ItinLocator is unknown, RecordLocator element should be passed instead. |
| RecordLocator | Y, if the ItinLocator is not sent | The GDS record locator. Should be passed only if the ItinLocator is unknown. |
| ApproverLogin | Y | The Travel approver's login ID. |
| Action | Y | The workflow action to take. Supported values are approve, reject. |
Examples
Example 1: Update a trip as approved with successful response
Request
POST /api/tws/v1.0/TripApproval/DoApproval HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
...
<TripApprovalRQ TransactionId="1cc6ea2d-c711-409e-bb51-63b2bdd485fc">
<Version>1.0</Version>
<ItinLocator>CQ-BB8-16JED-3ZW</ItinLocator>
<ApproverLogin>cm@example.com</ApproverLogin>
<Action>approve</Action>
</TripApprovalRQ>
Response
HTTPS/1.1 200 OK
Content-Type: application/xml
<TripApprovalRS TransactionId="1cc6ea2d-c711-409e-bb51-63b2bdd485fc">
<Version>1.0</Version>
<Status>success</Status>
</TripApprovalRS>
Example 2: Update a trip as approved with error
Request
POST /api/tws/v1.0/TripApproval/DoApproval HTTPS/1.1
Host: www.concursolutions.com
Authorization: OAuth {access token}
Content-Type: application/xml
<TripApprovalRQ TransactionId="1cc6ea2d-c711-409e-bb51-63b2bdd485fc">
<Version>1.0</Version>
<ItinLocator>CQ-BB8-16JED-3ZW</ItinLocator>
<ApproverLogin>cm@example.com</ApproverLogin>
<Action>approve</Action>
</TripApprovalRQ>
Response
HTTPS/1.1 200 OK
Content-Type: application/xml
<TripApprovalRS TransactionId="1cc6ea2d-c711-409e-bb51-63b2bdd485fc">
<Version>1.0</Version>
<Status>failure</Status>
<Error Code="506">No tripId found for this ItinLocator or RecordLocator.</Error>
</TripApprovalRS>
Error Codes
| Code | Description |
|---|---|
| 501 | TripId or ItinLocator is missing. |
| 503 | ManagerId is required. This is sometimes returned when the ApproverLogin is invalid. |
| 504 | Action is required. |
| 505 | Invalid Action (must be either approve or reject). |
| 506 | No tripId found for this ItinLocator or RecordLocator. |
| 507 | No request data. |
| 508 | Request data is not well formatted XML. |
| 509 | XML Validation Error. XML schema validation errors will be supplied, if available. |
| 510 | TripLocator or RecordLocator was not found |
| 600 | An error occured while approving the trip. |
| 700 | An error occured while rejecting the trip. |
Custom List Items
Custom list fields are included in many of the web services calls and they require some special consideration.
Value
When posting a list item, the list item code should be sent as the value, not the list item name. The code is returned in the levelxcode element of the Get List Items function.
Posting Connected List Items
There are two types of custom lists: Simple lists and Connected (multi-level) lists. If the list is a connected list, the list fields must be sent in sequential order, from parent to the lowest level child list item, as they are configured in the connected list definition.
Example: If your connected list uses Custom5 for the first level, Custom10 for the second level and Custom2 for the third level, you must send the XML elements for the custom fields in that order:
<Custom5>FirstValueCode</Custom5>
<Custom10>SecondValueCode</Custom10>
<Custom2>ThirdValueCode</Custom2>
Common Issues
Developers that post custom list item values can encounter errors when they post a list item that does not exist in the SAP Concur database. This can happen when the list item import hasn't been completed or hasn't run recently. If the posted list item code does not match an existing list item, the post may result in bad data. Use the List Item web service to ensure that the list items you are posting are present in the Concur database.